<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.8, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- newra (version 1, updated 2021 October 6)

(c) lloda 2017-2021

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<title>newra — An alternative array library for Guile 3</title>

<meta name="description" content="newra — An alternative array library for Guile 3">
<meta name="keywords" content="newra — An alternative array library for Guile 3">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="#Top" rel="start" title="Top">
<link href="#Indices" rel="index" title="Indices">
<link href="#Introduction" rel="next" title="Introduction">
<style type="text/css">
<!--
a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
span:hover a.copiable-anchor {visibility: visible}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<h1 class="settitle" align="center">newra — An alternative array library for Guile 3</h1>


















































<div class="top" id="Top">
<div class="header">
<p>
Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="newra"></span><h1 class="top"><code>newra</code></h1>

<p><code>newra</code> (version 1, updated 2021 October 6)
</p>
<p>(c) lloda 2017&ndash;2021
</p>
<div class="display">
<pre class="display">Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
</pre></div>

<p><code>newra</code> is a pure Scheme replacement for the built-in C-based array facility in Guile 3.0.
</p>
<p>This document uses ‘array’ to refer both to the old built-in array type and to the new type introduced in <code>newra</code>. The distinction is made as necessary.
</p>



<ul class="section-toc">
<li><a href="#Introduction" accesskey="1">Introduction</a></li>
<li><a href="#Low-level" accesskey="2">Low level</a></li>
<li><a href="#High-level" accesskey="3">High level</a></li>
<li><a href="#Hazards" accesskey="4">Hazards</a></li>
<li><a href="#Reference" accesskey="5">Reference</a></li>
<li><a href="#Cheatsheet" accesskey="6">Cheatsheet</a></li>
<li><a href="#Sources" accesskey="7">Sources</a></li>
<li><a href="#Indices" accesskey="8">Indices</a></li>
</ul>
<hr>
<div class="chapter" id="Introduction">
<div class="header">
<p>
Next: <a href="#Low-level" accesskey="n" rel="next">Low level</a>, Previous: <a href="#Top" accesskey="p" rel="prev"><code>newra</code></a>, Up: <a href="#Top" accesskey="u" rel="up"><code>newra</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Introduction-1"></span><h2 class="chapter">1 Introduction</h2>

<span id="index-bounds"></span>
<p>A multidimensional array is a container (or rather a container view) whose elements can be looked up using a multi-index (i₀, i₁, ...). Each of the indices i₀, i₁, ... has constant bounds [l₀, h₀], [l₁, h₁], ... independent of the values of the other indices, so the array is ‘rectangular’. The number of indices in the multi-index is the <em>rank</em> of the array, and the list ([l₀ h₀] [l₁ h₁] ... [lᵣ₋₁ hᵣ₋₁]) is the <em>shape</em> of the array. We speak of a rank-<em class='math'>r</em> array or of an <em class='math'>r</em>-array.
</p>
<p>This is a 2-array with bounds [0, 2] on both axes:
</p><pre class="verbatim">┌───────┬───────┬───────┐
│A(0, 0)│A(0, 1)│A(0, 2)│
├───────┼───────┼───────┤
│A(1, 0)│A(1, 1)│A(1, 2)│
├───────┼───────┼───────┤
│A(2, 0)│A(2, 1)│A(2, 2)│
└───────┴───────┴───────┘
</pre>
<p>This is a 3-array with bounds [0, 1] on axis 0, [2, 5] on axis 1, bounds [-2, 0] on axis 2:<a id="DOCF1" href="#FOOT1"><sup>1</sup></a>
</p><pre class="verbatim">║───────────┬───────────┬──────────║───────────┬───────────┬──────────║
║A(0, 2, -2)│A(0, 2, -1)│A(0, 2, 0)║A(1, 2, -2)│A(1, 2, -1)│A(1, 2, 0)║
║───────────┼───────────┼──────────║───────────┼───────────┼──────────║
║A(0, 3, -2)│A(0, 3, -1)│A(0, 3, 0)║A(1, 3, -2)│A(1, 3, -1)│A(1, 3, 0)║
║───────────┼───────────┼──────────║───────────┼───────────┼──────────║
║A(0, 4, -2)│A(0, 4, -1)│A(0, 4, 0)║A(1, 4, -2)│A(1, 4, -1)│A(1, 4, 0)║
║───────────┼───────────┼──────────║───────────┼───────────┼──────────║
║A(0, 5, -2)│A(0, 5, -1)│A(0, 5, 0)║A(1, 5, -2)│A(1, 5, -1)│A(1, 5, 0)║
║───────────┴───────────┴──────────║───────────┴───────────┴──────────║
</pre>
<p>Sometimes we deal with multidimensional <em>expressions</em> where the elements aren&rsquo;t stored anywhere, but are computed on demand when the expression is looked up. In this general sense, an ‘array’ is just a function of integers with a rectangular domain. Such an array would be immutable.
</p>
<p>Arrays (in the form of <em>matrices</em>, <em>vectors</em>, or <em>tensors</em>) are very common objects in math and programming, and it is very useful to be able to manipulate arrays as individual entities rather than as aggregates — that is one of the main purposes of <code>newra</code>.
</p>
<p>The rest of this section discusses the motivation for <code>newra</code> in more detail. To start using the library, please jump ahead to <a href="#Low-level">Low level</a>.
</p>

<ul class="section-toc">
<li><a href="#Rank-polymorphism" accesskey="1">Rank polymorphism</a></li>
<li><a href="#Rank-extension" accesskey="2">Rank extension</a></li>
<li><a href="#The-pieces-of-an-array" accesskey="3">The pieces of an array</a></li>
<li><a href="#Built_002din-Guile-arrays" accesskey="4">Built-in Guile arrays</a></li>
</ul>
<hr>
<div class="section" id="Rank-polymorphism">
<div class="header">
<p>
Next: <a href="#Rank-extension" accesskey="n" rel="next">Rank extension</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Rank-polymorphism-1"></span><h3 class="section">1.1 Rank polymorphism</h3>

<span id="index-rank-polymorphism"></span>
<p><em>Rank polymorphism</em> is the ability to treat an array of rank <em class='math'>r</em> as an array of lower rank where the elements are themselves arrays.
</p>
<span id="index-cell"></span>
<span id="index-frame"></span>
<p>Think of a matrix A, a 2-array with lengths (l₀, l₁) where the elements A(i₀, i₁) are numbers. If we consider the subarrays (rows) A(0, ...), A(1, ...), ..., A(l₀-1, ...) as individual elements, then we have a new view of A as a 1-array of length l₀ with those rows as elements. We say that the rows A(i₀)≡A(i₀, ...) are the 1-<em>cells</em> of A, and the numbers A(i₀, i₁) are 0-cells of A. For an array of arbitrary rank <em class='math'>r</em> the (<em class='math'>r</em>-1)-cells of A are called its <em>items</em>. The prefix of the shape (l₀, l₁, ... lₙ₋₁₋ₖ) that is not taken up by the k-cell is called the (r-k)-<em>frame</em>.
</p>
<table>
<tr><td width="40%"><pre class="verbatim">┌───────┬───────┬───────┐
│A(0, 0)│A(0, 1)│A(0, 2)│
├───────┼───────┼───────┤
│A(1, 0)│A(1, 1)│A(1, 2)│
├───────┼───────┼───────┤
│A(2, 0)│A(2, 1)│A(2, 2)│
└───────┴───────┴───────┘
</pre></td><td width="10%">≡</td><td width="40%"><pre class="verbatim">────
A(0)
────
A(1)
────
A(2)
────
</pre></td></tr>
</table>

<p>An obvious way to store an array in linearly addressed memory is to place its items one after another. So we would store a 3-array as
</p>
<blockquote>
<p>A: [A(0), A(1), ...]
</p></blockquote>

<p>and the items of A(i₀), etc. are in turn stored in the same way, so
</p>
<blockquote>
<p>A: [A(0): [A(0, 0), A(0, 1) ...], ...]
</p></blockquote>

<p>and the same for the items of A(i₀, i₁), etc.
</p>
<blockquote>
<p>A: [[A(0, 0): [A(0, 0, 0), A(0, 0, 1) ...], A(0, 1): [A(0, 1, 0), A(0, 1, 1) ...]], ...]
</p></blockquote>

<span id="index-order_002c-row_002dmajor"></span>
<span id="index-order_002c-C"></span>
<p>This way to lay out an array in memory is called <em>row-major order</em> or <em>C-order</em>, since it&rsquo;s the default order for built-in arrays in C. A row-major array A with lengths (l₀, l₁, ... lᵣ₋₁) can be looked up like this:
</p>
<span id="x_002dsteps"></span><blockquote>
<p>A(i₀, i₁, ...) = (storage-of-A) [(((i₀l₁ + i₁)l₂ + i₂)l₃ + ...)+iᵣ₋₁] = (storage-of-A) [o + s₀·i₀ + s₁·i₁ +  ...]
</p></blockquote>

<p>where the numbers (s₀, s₁, ...) are called the <em>steps</em><a id="DOCF2" href="#FOOT2"><sup>2</sup></a>. Note that the ‘linear’ or ‘raveled’ address [o + s₀·i₀ + s₁·i₁ +  ...] is an affine function of (i₀, i₁, ...). If we represent an array as a tuple
</p>
<blockquote>
<p>A ≡ ((storage-of-A), o, (s₀, s₁, ...))
</p></blockquote>

<p>then any affine transformation of the indices can be achieved simply by modifying the numbers (o, (s₀, s₁, ...)), with no need to touch the storage. This includes very common operations such as: <a href="#x_002dra_002dtranspose">transposing</a> axes, <a href="#x_002dra_002dreverse">reversing</a> the order along an axis, most cases of <a href="#Slicing">slicing</a>, and sometimes even reshaping or tiling the array.
</p>
<p>A basic example is obtaining the i₀-th item of A:
</p>
<blockquote>
<p>A(i₀) ≡ ((storage-of-A), o+s₀·i₀, (s₁, ...))
</p></blockquote>

<p>Note that we can iterate over these items by simply bumping the pointer o+s₀·i₀. This means that iterating over (k&gt;0)-cells doesn&rsquo;t have to cost any more than iterating over 0-cells (<a href="#x_002dra_002dslice_002dfor_002deach"><code>ra-slice-for-each</code></a>). Rank polymorphism isn&rsquo;t just a high level property of arrays; it is enabled and supported by the way they are laid out in memory.
</p>
<hr>
</div>
<div class="section" id="Rank-extension">
<div class="header">
<p>
Next: <a href="#The-pieces-of-an-array" accesskey="n" rel="next">The pieces of an array</a>, Previous: <a href="#Rank-polymorphism" accesskey="p" rel="prev">Rank polymorphism</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Rank-extension-1"></span><h3 class="section">1.2 Rank extension</h3>

<p>Rank extension is the mechanism that allows <code>R+S</code> to be defined even when <code>R</code>, <code>S</code> may have different ranks. The idea is an interpolation of the following basic cases.
</p>
<p>Suppose first that <code>R</code> and <code>S</code> have the same rank. We require that the shapes be the same. Then the shape of <code>R+S</code> will be the same as the shape of either <code>R</code> or <code>S</code> and the elements of <code>R+S</code> will be
</p>
<blockquote>
<p><code>(R+S)(i₀ i₁ ... i₍ᵣ₋₁₎) = R(i₀ i₁ ... i₍ᵣ₋₁₎) + S(i₀ i₁ ... i₍ᵣ₋₁₎)</code>
</p></blockquote>

<p>where <code>r</code> is the rank of <code>R</code>.
</p>
<p>Now suppose that <code>S</code> has rank 0. The shape of <code>R+S</code> is the same as the shape of <code>R</code> and the elements of <code>R+S</code> will be
</p>
<blockquote>
<p><code>(R+S)(i₀ i₁ ... i₍ᵣ₋₁₎) = R(i₀ i₁ ... i₍ᵣ₋₁₎) + S()</code>.
</p></blockquote>

<p>The two rules above are supported by all primitive array languages. But suppose that <code>S</code> has rank <code>s</code>, where <code>0&lt;s&lt;r</code>. Looking at the expressions above, it seems natural to define <code>R+S</code> by
</p>
<blockquote>
<p><code>(R+S)(i₀ i₁ ... i₍ₛ₋₁₎ ... i₍ᵣ₋₁₎) = R(i₀ i₁ ... i₍ₛ₋₁₎ ... i₍ᵣ₋₁₎) + S(i₀ i₁ ... i₍ₛ₋₁₎)</code>.
</p></blockquote>

<p>That is, after we run out of indices in <code>S</code>, we simply repeat the elements. We have aligned the shapes so:
</p>
<blockquote>
<pre class="verbatim">[n₀ n₁ ... n₍ₛ₋₁₎ ... n₍ᵣ₋₁₎]
[n₀ n₁ ... n₍ₛ₋₁₎]
</pre></blockquote>

<span id="index-shape-agreement_002c-prefix"></span>
<span id="index-shape-agreement_002c-suffix"></span>
<span id="index-Numpy"></span>
<p>This rank extension rule is used by the J language [<a href="#Sources">J S</a>]
 and is known as <em>prefix agreement</em>. The opposite rule of <em>suffix agreement</em> is used, for example, in Numpy [<a href="#Sources">num17</a>]
.
</p>
<p>As you can verify, the prefix agreement rule is distributive. Therefore it can be applied to nested expressions or to expressions with any number of arguments. It is applied systematically throughout <code>newra</code>, even in assignments. For example,
</p>
<div class="example">
<pre class="verbatim">(define a (make-ra-root #(3 5 9)))
(define b (make-ra #f 3 2))
(ra-copy! b a) ; copy each aᵢ on each bᵢ
</pre><pre class="example">&rArr; <code>#%2:3:2((3 3) (5 5) (9 9))</code>
</pre></div>

<div class="example">
<pre class="verbatim">(define a (make-ra 0 3))
(define b (ra-reshape (ra-iota 6 1) 0 3 2))
(ra-map! a + a b) ; sum the rows of b
</pre><pre class="example">&rArr; <code>#%1:3(3 7 11)</code>
</pre></div>

<span id="index-Numpy-1"></span>
<span id="index-broadcasting_002c-singleton_002c-newaxis"></span>
<p>A weakness of prefix agreement is that the axes you want to match aren&rsquo;t always the prefix axes. Other array systems (e.g. [<a href="#Sources">num17</a>]
) offer a feature similar to rank extension called ‘broadcasting’ that is a bit more flexible. For example an array of shape [A B 1 D] will match an array of shape [A B C D] for any value of C. The process of broadcasting consists in inserting so-called ‘singleton dimensions’ (axes with length one) to align the axes that one wishes to match. One may think of rank extension as a particular case of broadcasting where the singleton dimensions are added to the end of the shorter shapes automatically.
</p>
<p>A drawback of singleton broadcasting is that it muddles the distinction between a scalar and a vector of length 1. Sometimes, an axis of length 1 is no more than that, and if 2≠3 is a size error, it isn&rsquo;t obvious why 1≠2 shouldn&rsquo;t be. For this reason <code>newra</code>&rsquo;s support for explicit broadcasting is based on <a href="#x_002ddead_002daxes">dead axes</a>.
</p>
<div class="example">
<pre class="verbatim">(define a (ra-i 5 3))
(define b (make-ra 0 3))
(let ((b1 (ra-transpose b 1))) ; align axis 0 of b with axis 1 of a
  (ra-map! b1 + b1 a) ; sum the columns of a
  b)
</pre><pre class="example">&rArr; b = <code>#%1:5(30 35 40)</code>
</pre></div>

<hr>
</div>
<div class="section" id="The-pieces-of-an-array">
<div class="header">
<p>
Next: <a href="#Built_002din-Guile-arrays" accesskey="n" rel="next">Built-in Guile arrays</a>, Previous: <a href="#Rank-extension" accesskey="p" rel="prev">Rank extension</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="The-pieces-of-an-array-1"></span><h3 class="section">1.3 The pieces of an array</h3>

<p>An <code>newra</code> array is an aggregate of the following pieces:
</p>
<span id="index-rank"></span>
<span id="index-dim-vector"></span>
<span id="index-root-vector"></span>
<ul>
<li> A <em>root vector</em>, or root for short.
This can be a Scheme vector, as well as one of several other vector-like types.
</li><li> A <em>zero</em>.
An arbitary integer.
</li><li> A <em>dim vector</em>.
Each dim consists of a length (<em>len</em>), a lower bound (<em>lo</em>), and a <em>step</em>. The length of the dim vector is the <em>rank</em> of the array.
</li></ul>

<p>Together, the dim vector and the zero define an affine function of array indices <code>i₀, i₁, ..</code> that produces an index into the root. Thus, the array is a multidimensional view of the root.
</p>
<p>For example, the following pieces
</p>
<ul>
<li> root: v = <code>#(1 2 3 4 5 6 7)</code>
</li><li> zero: 1
</li><li> dims: <code>#(#&lt;&lt;dim&gt; len: 2 lo: 0 step: 2&gt; #&lt;&lt;dim&gt; len: 2 lo: 0 step: 1&gt;)</code>
</li></ul>

<p>define an array A(i₀, i₁) = v(1 + 2·i₀ + 1·i₁), 0≤i₀&lt;2, 0≤i₁&lt;2, that is A = [[2 3] [4 5]].
</p>
<p>In <code>newra</code> code,
</p>
<div class="example">
<pre class="verbatim">(make-ra-root (vector 1 2 3 4 5 6 7) 1 (vector (make-dim 2 0 2) (make-dim 2 0 1)))
</pre><pre class="example">&rArr; <code>#%2:2:2((2 3) (4 5))</code>
</pre></div>

<p>The default print style means <code>#%RANK:LEN₀:LEN₁(...)</code> (<a href="#Writing-and-reading">Writing and reading</a>).
</p>
<p>It&rsquo;s unusual to need to specify the dims directly. More commonly, one creates an array of whatever size
</p>
<div class="example">
<pre class="verbatim">&gt; (define a (make-ra #f 3 4))
&gt; a
</pre><pre class="example">&rArr; <code>#%2:3:4((#f #f #f #f) (#f #f #f #f) (#f #f #f #f))</code>
</pre></div>

<p>which automatically creates a root of the required size, so that all the array elements are distinct. Then one operates on the array without making reference to the underlying root,
</p>
<div class="example">
<pre class="verbatim">&gt; (ra-set! a 99 2 2)
</pre><pre class="example">&rArr; <code>#%2:3:4((#f #f #f #f) (#f #f 99 #f) (#f #f #f #f))</code>
</pre></div>

<p>Still, since the array is just a view of the root, any changes on the array are reflected there as well
</p>
<div class="example">
<pre class="verbatim">&gt; (ra-root a)
</pre><pre class="example">&rArr; <code>#(#f #f #f #f #f #f #f #f #f #f 99 #f)</code>
</pre></div>

<p>and the other way around,
</p>
<div class="example">
<pre class="verbatim">&gt; (define b (make-ra-root (vector 'x) 0 (vector (make-dim 3 0 0) (make-dim 2 0 0))))
&gt; b
</pre><pre class="example">&rArr; <code>#%2:3:2((x x) (x x) (x x))</code>

</pre><pre class="verbatim">&gt; (vector-set! (ra-root b) 0 'Z)
&gt; b
</pre><pre class="example">&rArr; <code>#%2:3:2((Z Z) (Z Z) (Z Z))</code>
</pre></div>

<span id="index-shared-root"></span>
<span id="index-new-array"></span>
<p>It is often important to know whether an operation on an array returns a different view of its argument, or instead it allocates a new root which can be modified without affecting the original argument. When we say that a function &lsquo;creates a new array&rsquo;, we mean that it allocates a new root.
</p>
<p>Generally a given function will always do one or the other, e.g. the result of <a href="#x_002dra_002dtile"><code>ra-tile</code></a> always shares the root of its argument, while <a href="#x_002dra_002dcopy"><code>ra-copy</code></a> always creates a new array. Some functions, like <a href="#x_002dra_002dravel"><code>ra-ravel</code></a> or <a href="#x_002dra_002dfrom"><code>ra-from</code></a>, may do either, depending on their arguments. For example, the result of
</p>
<div class="example">
<pre class="verbatim">(ra-ravel (ra-iota 3 4))
</pre><pre class="example">&rArr; <code>#%1d:12(0 1 2 3 4 5 6 7 8 9 10 11)</code>
</pre></div>

<p>shares the root of <code>(ra-iota 3 4)</code>, but
</p>
<div class="example">
<pre class="verbatim">(ra-ravel (ra-transpose (ra-iota 3 4) 1 0))
</pre><pre class="example">&rArr; <code>#%1:12(0 4 8 1 5 9 2 6 10 3 7 11)</code>
</pre></div>

<p>doesn&rsquo;t.
</p>
<hr>
</div>
<div class="section" id="Built_002din-Guile-arrays">
<div class="header">
<p>
Previous: <a href="#The-pieces-of-an-array" accesskey="p" rel="prev">The pieces of an array</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Built_002din-Guile-arrays-1"></span><h3 class="section">1.4 Built-in Guile arrays</h3>

<p>Dense multidimensional arrays work similarly in every language that offers them, and built-in Guile arrays are no different — they also have a root (<code>shared-array-root</code>), a zero (computable from <code>shared-array-offset</code> and <code>array-shape</code>), and a dim vector (<code>array-shape</code>, <code>shared-array-increments</code>). Functionally, they are entirely equivalent to the objects offered by <code>newra</code>. Why replace them?
</p>
<span id="index-libguile"></span>
<p>Built-in Guile arrays are implemented in C, as part of libguile. As a Guile type they have their own low-level type tag, and all the basic array operations are C stubs, even the most basic functions such as <code>array-ref</code> or <code>array-rank</code>. Obtaining any of the components of the array requires calling into C. There are several problems with this.
</p>
<p>First, the built-in library offers a single function to manipulate array dims, <code>make-shared-array</code>. Although this is a sufficient interface, it is excessively generic, and also very cumbersome and inefficient. The array dims cannot be manipulated directly from Scheme, so any alternative interface written in Scheme is forced to go through <code>make-shared-array</code>.
</p>
<p>Second, the C stubs create a barrier to optimization by the Scheme compiler. The main loop of an operation such as <code>(array-map! c + a b)</code> has to be implemented in C (for the reasons given above) and then it has to call back to Scheme on each iteration in order to apply <code>+</code>. Since the Scheme compiler doesn&rsquo;t have any special support for <code>array-map!</code>, it doesn&rsquo;t know what the types of the arguments are, etc. and those checks and dispatches are repeated over and over. <a id="DOCF3" href="#FOOT3"><sup>3</sup></a>
</p>
<p>Third, some of the the larger functions of the array interface, such as <code>array-map!</code>, etc. are not interruptible. This is especially inconvenient when operating on large arrays.
</p>
<p>These problems are solved if the built-in type is replaced with a new type defined in Scheme.
</p>
<hr>
</div>
</div>
<div class="chapter" id="Low-level">
<div class="header">
<p>
Next: <a href="#High-level" accesskey="n" rel="next">High level</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up"><code>newra</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Low-level-1"></span><h2 class="chapter">2 Low level</h2>


<ul class="section-toc">
<li><a href="#Creating-and-accessing-arrays" accesskey="1">Creating and accessing arrays</a></li>
<li><a href="#Special-arrays" accesskey="2">Special arrays</a></li>
<li><a href="#Writing-and-reading" accesskey="3">Writing and reading</a></li>
<li><a href="#Iteration" accesskey="4">Iteration</a></li>
<li><a href="#Slicing" accesskey="5">Slicing</a></li>
<li><a href="#Reshaping" accesskey="6">Reshaping</a></li>
<li><a href="#Concatenation" accesskey="7">Concatenation</a></li>
<li><a href="#Transposition" accesskey="8">Transposition</a></li>
<li><a href="#Other-operations-on-arrays" accesskey="9">Other operations on arrays</a></li>
<li><a href="#Automatic-result-arrays">Automatic result arrays</a></li>
<li><a href="#Foreign-interface">Foreign interface</a></li>
<li><a href="#Compatibility-with-old-Guile-arrays">Compatibility with old Guile arrays</a></li>
</ul>
<hr>
<div class="section" id="Creating-and-accessing-arrays">
<div class="header">
<p>
Next: <a href="#Special-arrays" accesskey="n" rel="next">Special arrays</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Creating-and-accessing-arrays-1"></span><h3 class="section">2.1 Creating and accessing arrays</h3>

<p>An array can be created anew (<a href="#x_002dmake_002dra_002dnew"><code>make-ra-new</code></a>, <a href="#x_002dmake_002dra"><code>make-ra</code></a>, <a href="#x_002dmake_002dtyped_002dra"><code>make-typed-ra</code></a>), or over an existing root (<a href="#x_002dmake_002dra_002droot"><code>make-ra-root</code></a>).
</p>
<p><a href="#x_002dmake_002dra"><code>make-ra</code></a> or <a href="#x_002dmake_002dtyped_002dra"><code>make-typed-ra</code></a> take array lengths and use row-major order by default.
</p>
<div class="example">
<pre class="verbatim">(make-ra 99 2 3)
</pre><pre class="example">&rArr; #%2:3:2((9 9) (9 9) (9 9))
</pre></div>

<div class="example">
<pre class="verbatim">(make-typed-ra 'f64 99 2 3)
</pre><pre class="example">&rArr; #%2f64:3:2((9.0 9.0) (9.0 9.0) (9.0 9.0))
</pre></div>

<p><a href="#x_002dmake_002dra_002dnew"><code>make-ra-new</code></a> takes an array type, a fill value, and a dim vector. <a href="#x_002dc_002ddims"><code>c-dims</code></a> can be used to create a row-major dim vector.
</p>
<div class="example">
<pre class="verbatim">(make-ra-new #t 'x (vector (make-dim 3 0 2) (make-dim 2 0 1))) ; more simply
(make-ra-new #t 'x (c-dims 3 2))
</pre><pre class="example">&rArr; #%2:3:2((x x) (x x) (x x))
</pre></div>

<div class="example">
<pre class="verbatim">(make-ra-new 'f32 0.0 (c-dims 3 2))
</pre><pre class="example">&rArr; #%2f32:3:2((0.0 0.0) (0.0 0.0) (0.0 0.0))
</pre></div>

<p><a href="#x_002dmake_002dra_002droot"><code>make-ra-root</code></a> takes the type from the root vector.
</p>
<div class="example">
<pre class="verbatim">(make-ra-root (vector 1 2 3 4 5 6) (c-dims 3 2))
</pre><pre class="example">&rArr; #%2:3:2((1 2) (3 4) (5 6))
</pre></div>

<p><code>newra</code> arrays are applicative; to look up or assign an element of an array, use it as a function of the indices.
</p>
<div class="example">
<pre class="verbatim">(define a (make-ra #f 3 2))
(set! (a 0 0) 9)
(set! (a 1 1) 3)
</pre><pre class="example">&rArr; #%2:3:4((9 #f) (#f 3) (#f #f))
</pre><pre class="verbatim">(a 0 0)
</pre><pre class="example">&rArr; 9
</pre></div>

<span id="index-prefix-slice"></span>
<p>If you give fewer indices than the rank, you get a prefix slice. This slice shares the root of the original array.
</p>
<div class="example">
<pre class="verbatim">(a 1)
</pre><pre class="example">&rArr; #%1:2(#f 3)
</pre><pre class="verbatim">(set! ((a 1) 0) 'b)
</pre><pre class="example">&rArr; #%1:2(b 3)
</pre><pre class="verbatim">a
</pre><pre class="example">&rArr; #%2:3:4((9 #f) (b 3) (#f #f))
</pre></div>

<p>You can also access arrays in the more usual way with the functions <a href="#x_002dra_002dref"><code>ra-ref</code></a> and <a href="#x_002dra_002dset_0021"><code>ra-set!</code></a>. See <a href="#Slicing">Slicing</a> for additional options.
</p>
<hr>
</div>
<div class="section" id="Special-arrays">
<div class="header">
<p>
Next: <a href="#Writing-and-reading" accesskey="n" rel="next">Writing and reading</a>, Previous: <a href="#Creating-and-accessing-arrays" accesskey="p" rel="prev">Creating and accessing arrays</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Special-arrays-1"></span><h3 class="section">2.2 Special arrays</h3>

<p>Any type that is usable as the root of an old built-in Guile array is also usable as root of a <code>newra</code> array. These include
</p>
<ul>
<li> vectors (e.g. <code>(vector 3)</code>)
</li><li> SRFI-4 typed vectors (e.g. <code>(c64vector 1 2+0i)</code>)
</li><li> strings (e.g. <code>&quot;hello&quot;</code>)
</li><li> bitvectors (e.g. <code>(bitvector #f #t #f #t)</code>)
</li></ul>

<p><code>newra</code> supports an additional root vector type, <code>&lt;aseq&gt;</code>, representing an unbounded arithmetic sequence.
</p>
<span id="index-make_002daseq"></span>
<span id="x_002dnone"></span><dl class="def">
<dt id="index-make_002daseq-1"><span class="category">Function<!-- /@w -->: </span><span><strong>make-aseq</strong> <em>[org [inc]]</em><a href='#index-make_002daseq-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Create an arithmetic sequence [<code>org, org+inc, org+2·inc, ...</code>]. The default values of <code>org</code> and <code>inc</code> are respectively 0 and 1. For example:
</p>
<div class="example">
<pre class="verbatim">(make-ra-root (make-aseq 0 3) (vector (make-dim 10)) 0)
</pre><pre class="example">&rArr; #%1d:10(0 3 6 9 12 15 18 21 24 27)
</pre></div>

<p>(The example above can be written <code>(<a href="#x_002dra_002diota">ra-iota</a> 10 0 3)</code>).
</p></dd></dl>

<span id="index-d"></span>
<p><code>aseq</code> roots are immutable. The type tag of <code>aseq</code> roots is <code>d</code>. Arrays with integer-valued <code>aseq</code> roots have a few special uses; one of them is as arguments in <a href="#Slicing">slicing</a>.
</p>
<span id="index-infinite-axes"></span>
<span id="index-unbounded-axes"></span>
<p>To make <code>&lt;aseq&gt;</code> even more useful, <code>newra</code> supports unbounded axes.
</p>
<div class="example">
<pre class="verbatim">(ra-ref (make-ra-root (make-aseq) (vector (make-dim #f)) 0) #e1e12) ; or more simply
(ra-ref (ra-iota) #e1e12)
</pre><pre class="example">&rArr; 1000000000000
</pre></div>

<p>These are treated especially when used in iteration, in that they match axes of any finite length (<a href="#x_002dra_002dmap_0021"><code>ra-map!</code></a>). Effectively this lets one use <code>(<a href="#x_002dra_002dtranspose"><code>ra-transpose</code></a> (ra-iota) k)</code> as a placeholder for the index over axis <code>k</code>.
</p>
<div class="example">
<pre class="verbatim">(ra-map! (make-ra 0 3) + (ra-iota 3) (ra-iota))
</pre><pre class="example">&rArr; #1%3(0 2 4)
</pre></div>

<span id="index-dead-axes"></span>
<span id="x_002ddead_002daxes"></span><p><code>newra</code> also supports &lsquo;dead axes&rsquo;, which are axes with step 0 and undefined length. These axes can match axes of any length and can exist on arrays of any type, not only on arrays of type <code>d</code>, because effectively only one position (the lower bound) is ever accessed.
</p>
<span id="index-singleton-axis"></span>
<p>Dead axes operate essentially as ‘singleton axes’ do in other array languages. The main diference is that the ability to match any finite length is explicit; an axis with length 1 will still fail to match an axis with length 2 (say).
</p>
<p>Some functions work by creating axes with step 0, usually with defined lengths.
</p>
<div class="example">
<pre class="verbatim">(define A (make-ra-root #(1 2 3) (c-dims 3)))
(ra-tile A 0 2 2)
</pre><pre class="example">&rArr; #%3d:2:2:3(((0 1 2) (0 1 2)) ((0 1 2) (0 1 2)))
</pre><pre class="verbatim">(ra-dims (ra-tile A 0 2 2))
</pre><pre class="example">&rArr; #(#&lt;&lt;dim&gt; len: 2 lo: 0 step: 0&gt; #&lt;&lt;dim&gt; len: 2 lo: 0 step: 0&gt; #&lt;&lt;dim&gt; len: 3 lo: 0 step: 1&gt;)
</pre></div>

<hr>
</div>
<div class="section" id="Writing-and-reading">
<div class="header">
<p>
Next: <a href="#Iteration" accesskey="n" rel="next">Iteration</a>, Previous: <a href="#Special-arrays" accesskey="p" rel="prev">Special arrays</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Writing-and-reading-1"></span><h3 class="section">2.3 Writing and reading</h3>

<p>The read syntax for arrays is <a href="https://www.gnu.org/software/guile/manual/html_node/Array-Syntax.html">the same</a> as for built-in Guile arrays, except that <code>#%</code> is used instead of <code>#</code>. Full dimensions are printed by default, even when they are not required to read an array.
</p>
<div class="example">
<pre class="verbatim">(call-with-input-string &quot;#%1(2 2 2)&quot; read)
</pre><pre class="example">&rArr; <code>#%1:3(2 2 2)</code>
</pre></div>

<div class="example">
<pre class="verbatim">(call-with-input-string &quot;#%1:3(2 2 2)&quot; read)
</pre><pre class="example">&rArr; <code>#%1:3(2 2 2)</code>
</pre></div>

<p>Dead axes print as <code>d</code>, and unbounded (not dead) axes print as <code>f</code>. These cannot be read back.
</p>
<div class="example">
<pre class="verbatim">(display (ra-transpose (ra-copy (ra-iota 3)) 1))
</pre><pre class="example">&rArr; <code>#%2:d:3((0 1 2))</code>
</pre></div>

<p>Arrays with root of type <code>d</code> cannot be read back either.
</p>
<div class="example">
<pre class="verbatim">(define s (format #f &quot;~a&quot; (ra-i 2 3)))
s
</pre><pre class="example">&rArr; <code>&quot;#%2d:2:3((0 1 2) (3 4 5))&quot;</code>
</pre></div>

<div class="example">
<pre class="verbatim">(call-with-input-string s read)
</pre><pre class="example">&rArr; error: cannot make array of type d
</pre></div>

<p>Truncated output is not supported yet.
</p>
<div class="example">
<pre class="verbatim">(format #f &quot;~@y&quot; (ra-i 2 3))
</pre><pre class="example">&rArr; <code>&quot;#%2d:2:3((0 1 2) (3 4 5))&quot;</code> ; ok, but we didn't need to truncate
</pre></div>

<div class="example">
<pre class="verbatim">(format #f &quot;~@y&quot; (ra-i 99 99))
</pre><pre class="example">&rArr; <code>&quot;#&quot; ; ouch</code>
</pre></div>

<p>The function <a href="#x_002dra_002dformat"><code>ra-format</code></a> can be used to pretty print arrays. This type of output cannot be read back, either.
</p>
<div class="example">
<pre class="verbatim">(ra-format (list-&gt;ra 2 '((1 hello) (&quot;try&quot; 2) (never 3.14))) #:fmt &quot;~s&quot;)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2:3:2─────┐
│    1│hello│
├─────┼─────┤
│&quot;try&quot;│    2│
├─────┼─────┤
│never│ 3.14│
└─────┴─────┘
</pre></div>

<p>The writing mode can be configured with the following parameter.
</p>
<span id="index-_002ara_002dprint_002a"></span>
<span id="x_002dstar_002dra_002dprint_002dstar"></span><dl class="def">
<dt id="index-_002ara_002dprint_002a-1"><span class="category">Parameter<!-- /@w -->: </span><span><strong>*ra-print*</strong> <em>(lambda (array port) ...)</em><a href='#index-_002ara_002dprint_002a-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Set the default printer for arrays. This parameter is available from <code>(newra print)</code>.
</p>
<span id="index-box"></span>
<span id="index-box_002dcompact"></span>
<span id="index-default"></span>
<p>The parameter can be set to a function <code>(lambda (array port) ...)</code> or to one of the values <code>#f</code>, <code>'default</code>, <code>'box</code> or <code>'box-compact</code>.
</p>
<p>For example
</p><div class="example">
<pre class="verbatim">(import (newra print))
(*ra-print* (lambda (ra o) (ra-print ra o #:dims? #f)))
(ra-i 2 3)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">$1 = #%2d((0 1 2) (3 4 5))
</pre></div>

<p>or
</p>
<div class="example">
<pre class="verbatim">(*ra-print* (lambda (ra o) (newline o) (ra-format ra o)))
; (*ra-print* 'box) ; same thing
(ra-i 2 3)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">$1 =
#%2d:2:3
│0│1│2│
├─┼─┼─┤
│3│4│5│
└─┴─┴─┘
</pre></div>

<p>The default printer can be reset with <code>(*ra-print* #f)</code> or <code>(*ra-print* 'default)</code>.
</p></dd></dl>

<span id="index-SRFI_002d163"></span>
<p>By default, rank-0 arrays are printed like the built-in Guile arrays, with extra parentheses around the content. In the read syntax specified in [<a href="#Sources">SRFI-163</a>]
, those parentheses are not used. The following parameter allows one to choose either behavior for both the printer and the reader.
</p>
<span id="index-_002ara_002dparenthesized_002drank_002dzero_002a"></span>
<span id="x_002dstar_002dra_002dparenthesized_002drank_002dzero_002dstar"></span><dl class="def">
<dt id="index-_002ara_002dparenthesized_002drank_002dzero_002a-1"><span class="category">Parameter<!-- /@w -->: </span><span><strong>*ra-parenthesized-rank-zero*</strong> <em>boolean</em><a href='#index-_002ara_002dparenthesized_002drank_002dzero_002a-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Control read syntax of rank-0 arrays. This parameter is available from <code>(newra print)</code> or <code>(newra read)</code>.
</p>
<p>If <code>(*ra-parenthesized-rank-zero*)</code> is true, the read syntax for rank-0 arrays is
</p>
<div class="display">
<pre class="display"><code>#%0TYPE(item)</code>
</pre></div>

<p>If it is <code>#f</code>, it is
</p>
<div class="display">
<pre class="display"><code>#%0TYPE item</code>
</pre></div>

<p>with <code>TYPE</code> being optional in either case. Note that these are not compatible:
</p>
<div class="example">
<pre class="verbatim">(ra-ref (parameterize ((*ra-parenthesized-rank-zero* #t))
          (call-with-input-string &quot;#%0(a)&quot; read)))
</pre><pre class="example">&rArr; <code>a</code>
</pre><pre class="verbatim">(ra-ref (parameterize ((*ra-parenthesized-rank-zero* #f))
          (call-with-input-string &quot;#%0(a)&quot; read)))
</pre><pre class="example">&rArr; <code>(a)</code>
</pre><pre class="verbatim">(ra-ref (parameterize ((*ra-parenthesized-rank-zero* #f))
          (call-with-input-string &quot;#%0 a&quot; read)))
</pre><pre class="example">&rArr; <code>a</code>
</pre></div>

<p>In the last example, the space is necessary (unlike in [<a href="#Sources">SRFI-163</a>]
) since the array type tag is optional in Guile.
</p>
<div class="example">
<pre class="verbatim">(parameterize ((*ra-parenthesized-rank-zero* #f))
  (call-with-input-string &quot;#%0a&quot; read))
</pre><pre class="example">&rArr; Wrong type (expecting character): #&lt;eof&gt;
</pre></div>

<p>The printer always uses a space in this mode:
</p>
<div class="example">
<pre class="verbatim">(parameterize ((*ra-parenthesized-rank-zero* #f))
 (display (make-ra '(a))))
</pre><pre class="example">&rArr; <code>#%0 (a)</code>
</pre></div>

<p>Note that setting this parameter to <code>#f</code> still doesn&rsquo;t make the array read syntax fully compatible with that of [<a href="#Sources">SRFI-163</a>]
, since the type tag <code>a</code> is reserved (in Guile) for character arrays.
</p>
<p>The default value of this parameter is <code>#t</code>.
</p>
</dd></dl>

<hr>
</div>
<div class="section" id="Iteration">
<div class="header">
<p>
Next: <a href="#Slicing" accesskey="n" rel="next">Slicing</a>, Previous: <a href="#Writing-and-reading" accesskey="p" rel="prev">Writing and reading</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Iteration-1"></span><h3 class="section">2.4 Iteration</h3>

<p>The basic array iteration operations in <code>newra</code> all operate by effect. This gives you control of how the result is allocated. If one of the arguments is designated as destination, as is the case with <a href="#x_002dra_002dmap_0021"><code>ra-map!</code></a>, then that is the result of the whole iteration. For example:
</p>
<div class="example">
<pre class="verbatim">(ra-map! (make-ra #f 3) - (ra-iota 3 1))
</pre><pre class="example">&rArr; #%1:3(-1 -2 -3)
</pre></div>

<p>It is common to need the indices of the elements during array iteration. <code>newra</code> iteration operations do not keep track of those indices<a id="DOCF4" href="#FOOT4"><sup>4</sup></a> because that has a cost. You need to pass the indices you need as arguments, but it&rsquo;s easy to do so by using an unbounded index vector together with <a href="#x_002dra_002dtranspose"><code>ra-transpose</code></a>.
</p>
<div class="example">
<pre class="verbatim">(define i0 (ra-iota))
(define i1 (ra-transpose (ra-iota) 1))
(ra-map! (make-ra #f 2 2) list (list-&gt;ra 2 '((A B) (C D))) i0 i1)
</pre><pre class="example">&rArr; #%2:2:2(((A 0 0) (B 0 1)) ((C 1 0) (D 1 1)))
</pre></div>

<p>One can iterate not only over the whole array, but also over any <code>n</code>-frame (the first <code>n</code> axes of an array), using <a href="#x_002dra_002dslice_002dfor_002deach"><code>ra-slice-for-each</code></a>. In this case the operation takes array slices as arguments, even when they are of rank 0; this allows writing to any of the arguments. When there are several arrays involved, all the frames must match.
</p>
<p>In the following example, <code>xys</code> is of rank 2, <code>angle</code> is of rank 1, and their first axes have the same length.
</p>
<div class="example">
<pre class="verbatim">(ra-slice-for-each 1
  (lambda (xy angle)
; inside the op, xy is rank 1, angle is rank 0
    (ra-set! angle (atan (ra-ref xy 1) (ra-ref xy 0))))
  xys angles)
</pre></div>

<span id="index-prefix-matching"></span>
<p>The iteration procedures in <code>newra</code> all perform rank extension of their arguments through prefix matching (see <a href="#Rank-extension">Rank extension</a>). In the following example, the shapes of the arguments are (5 5), (5) and (<code>#f</code> 5), and the common prefixes all match.
</p>
<div class="example">
<pre class="verbatim">(ra-map! (make-ra 5 5) * (ra-iota 5 1) (ra-transpose (ra-iota 5 1) 1))
</pre><pre class="example">&rArr; <code>#%2:5:5((1 2 3 4 5) (2 4 6 8 10) (3 6 9 12 15) (4 8 12 16 20) (5 10 15 20 25))</code>
</pre></div>

<p>Another example using <a href="#x_002dra_002dcopy_0021"><code>ra-copy!</code></a>,
</p>
<div class="example">
<pre class="verbatim">(ra-copy! (list-&gt;ra 2 '((a b) (p q) (x y)))
          (list-&gt;ra 1 '(1 2 3)))
</pre><pre class="example">&rArr; <code>#%2:3:2((1 1) (2 2) (3 3))</code>
</pre></div>

<hr>
</div>
<div class="section" id="Slicing">
<div class="header">
<p>
Next: <a href="#Reshaping" accesskey="n" rel="next">Reshaping</a>, Previous: <a href="#Iteration" accesskey="p" rel="prev">Iteration</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Slicing-1"></span><h3 class="section">2.5 Slicing</h3>

<p>Slicing refers to the operation of taking a partial view of an array (e.g. a row or a column out of a matrix) through modification of the dim vector. This can be done with creative uses of <a href="#x_002dra_002dravel"><code>ra-ravel</code></a>, <a href="#x_002dra_002dreshape"><code>ra-reshape</code></a> and <a href="#x_002dra_002dtranspose"><code>ra-transpose</code></a>, and of course by direct modification of the dim vector, but the facilities described in this section are usually a lot clearer.
</p>
<span id="index-prefix-slice-1"></span>
<p>The simplest form of slicing uses <a href="#x_002dra_002dslice">ra-slice</a> to produce ‘prefix slices’.
</p>
<div class="example">
<pre class="verbatim">(define a (list-&gt;ra 3 '(((a b) (x y)) ((A B) (X Y)))))
</pre><pre class="example">&rArr; <code>#%3:2:2:2(((a b) (x y)) ((A B) (X Y)))</code>
</pre><pre class="verbatim">(ra-slice a 0 1 0)
</pre><pre class="example">&rArr; <code>#%0(x)</code>
</pre><pre class="verbatim">(ra-slice a 0 1)
</pre><pre class="example">&rArr; <code>#%1:2(x y)</code>
</pre><pre class="verbatim">(ra-slice a 0)
</pre><pre class="example">&rArr; <code>#%2:2:2((a b) (x y))</code>
</pre><pre class="verbatim">(ra-slice a)
</pre><pre class="example">&rArr; <code>#%3:2:2:2(((a b) (x y)) ((A B) (X Y)))</code>
</pre></div>

<p>The prefix slice always shares the root of the source array, so it can be used to modify the source array.
</p>
<div class="example">
<pre class="verbatim">(ra-fill! (ra-slice a 1 0) '99)
</pre><pre class="example">&rArr; <code>#%1:2(99 99)</code>
</pre><pre class="verbatim">a
</pre><pre class="example">&rArr; <code>#%3:2:2:2(((a b) (x y)) ((99 99) (X Y)))</code>
</pre></div>

<p>The variant <a href="#x_002dra_002dcell"><code>ra-cell</code></a> is identical to <code>ra-slice</code> except that it returns an element (and not a rank 0 array) when the full set of indices is given.
</p>
<div class="example">
<pre class="verbatim">(ra-slice a 0 1 0)
</pre><pre class="example">&rArr; <code>x</code>
</pre></div>

<p><code>ra-cell</code> is a <a href="#Rank-polymorphism">rank-polymorphic</a> generalization of the basic element lookup function <a href="#x_002dra_002dref"><code>ra-ref</code></a>, which requires the full set of indices.
</p>
<div class="example">
<pre class="verbatim">(ra-ref a 0 1 0) ; same as ra-cell
</pre><pre class="example">&rArr; <code>x</code>
</pre><pre class="verbatim">(ra-ref a 0 1)
</pre><pre class="example">&rArr; <code>&quot;&lt;unnamed port&gt;&quot;:...: Throw to key `bad-number-of-indices' with args `(3 2)'.</code>
</pre></div>

<p>Both <code>ra-cell</code> and <code>ra-slice</code> (and <code>ra-ref</code>) take scalar indices as arguments. The more powerful function <a href="#x_002dra_002dfrom"><code>ra-from</code></a> is able to handle arrays of indices.
</p>
<span id="index-_007b_002c-from"></span>
<blockquote>
<pre class="verbatim">(ra-from a i₀ ...) ⇒ b
</pre></blockquote>

<p>Each of the <code>i₀...</code> is either 1. an integer; 2. an array of integers; 3. the special value <code>#t</code>. Integer arguments contain indices into the respective axis of <code>a</code>. <code>#t</code> for <code>iₖ</code> is a shortcut for ‘the whole of axis <code>k</code>’<a id="DOCF5" href="#FOOT5"><sup>5</sup></a>. The result <code>b</code> has rank equal to the sum of all the ranks of the <code>i₀...</code>, and is defined as
</p>
<blockquote>
<pre class="verbatim">(ra-ref b j₀ ...) = (ra-ref a (ra-ref i₀ j₀ ...) ...)
</pre></blockquote>

<p>In other words, <code>ra-from</code> produces the outer product of the indices <code>i₀...</code> with operator <code>a</code> (if one thinks of <code>(a i₀ ...)</code> as <code>(ra-ref a i₀ ...)</code>).
</p>
<p>If all of the <code>i...</code> are integers or arrays of type <code>d</code> (such as those produced by <code>ra-iota</code> or <code>ra-i</code>) then the result of <code>ra-from</code> shares the root of <code>a</code>. Otherwise <code>newra</code> cannot tell whether the indices are an arithmetic sequence, so the result has to be copied to a new root. For example:
</p>
<div class="example">
<pre class="verbatim">(define a (list-&gt;ra 2 '((a b c) (d e f))))
</pre><pre class="example">&rArr; <code>#%2:2:3((a b c) (d e f))</code>
</pre><pre class="verbatim">(ra-from a 0 #t) ; row 0, will share root
</pre><pre class="example">&rArr; <code>#%1:3(a b c)</code>
</pre><pre class="verbatim">(ra-from a #t 1) ; column 1, will share root
</pre><pre class="example">&rArr; <code>#%1:2(b e)</code>
</pre><pre class="verbatim">(ra-from a #t (make-ra-root #(2 0))) ; cols 2 &amp; 0, won't share root
</pre><pre class="example">&rArr; <code>#%2:2:2((c a) (f d))</code>
</pre><pre class="verbatim">(ra-from a #t (ra-iota 2 2 -2)) ; cols 2 &amp; 0, will share root
</pre><pre class="example">&rArr; <code>#%2:2:2((c a) (f d))</code>
</pre></div>

<p>One may give fewer <code>i</code> than the rank of <code>a</code>. The missing arguments are taken as <code>#t</code> (see <a href="#Rank-polymorphism">Rank polymorphism</a>).
</p>
<div class="example">
<pre class="verbatim">(ra-from a 0) ; row 0, same as (ra-from a 0 #t)
</pre><pre class="example">&rArr; <code>#%1d:3(0 1 2)</code>
</pre></div>

<span id="index-ldots"></span>
<p>When used as an argument to <code>ra-from</code> (or <code>ra-amend!</code>), the special object <code>(<a href="#x_002dldots">ldots</a> n)</code> stands for <code>n</code> times <code>#t</code>. <code>(ldots)</code> alone will expand to fill the rank of the array argument, so the indices that come after are pushed to the last axes.
</p>
<div class="example">
<pre class="verbatim">(ra-from A 0 (ldots 1) 1) ; same as (ra-from A 0 #t 1)
(ra-from B 0 (ldots 2) 1) ; same as (ra-from B 0 #t #t 1)
(ra-from C 0 (ldots) 1) ; same as (ra-from C 1 (ldots (- (ra-rank C) 2)) 1)
</pre></div>

<p>For instance:
</p><div class="example">
<pre class="verbatim">(ra-i 4 3 2)
</pre><pre class="example">&rArr; #%3d:4:3:2(((0 1) (2 3) (4 5)) ((6 7) (8 9) (10 11)) ((12 13) (14 15) (16 17)) ((18 19) (20 21) (22 23)))
</pre><pre class="verbatim">(ra-from (ra-i 4 3 2) (ldots) 1) ; select second element on last axis
</pre><pre class="example">&rArr; #%2d:4:3((1 3 5) (7 9 11) (13 15 17) (19 21 23))
</pre></div>

<p>When it is known that the result of <code>ra-from</code> will share the root with its argument, that can be used to modify the original array. For example:
</p>
<div class="example">
<pre class="verbatim">(ra-fill! (ra-from a 1) x)
</pre><pre class="example">&rArr; <code>#%2:3((a b c) (x x x)</code>
</pre><pre class="verbatim">a
</pre><pre class="example">&rArr; <code>#%2:3((a b c) (x x x))</code>
</pre></div>

<p><a href="#x_002dra_002damend_0021"><code>ra-amend!</code></a> handles the general case:
</p>
<div class="example">
<pre class="verbatim">(define a (list-&gt;ra 2 '((a b c) (d e f))))
(ra-amend! a 'Y #t (make-ra-root #(2 0)))
</pre><pre class="example">&rArr; <code>#%2:3((Y b Y) (Y e Y))</code>
</pre><pre class="verbatim">a
</pre><pre class="example">&rArr; <code>#%2:3((Y b Y) (Y e Y))</code>
</pre></div>
<p>while on the other hand
</p><div class="example">
<pre class="verbatim">(define a (list-&gt;ra 2 '((a b c) (d e f))))
(ra-fill! (ra-from a #t (make-ra-root #(2 0))) 'Y)
</pre><pre class="example">&rArr; <code>#%2:3((Y Y) (Y Y))</code>
</pre><pre class="verbatim">a
</pre><pre class="example">&rArr; <code>#%2:3((a b c) (d e f))</code>
</pre></div>

<hr>
</div>
<div class="section" id="Reshaping">
<div class="header">
<p>
Next: <a href="#Concatenation" accesskey="n" rel="next">Concatenation</a>, Previous: <a href="#Slicing" accesskey="p" rel="prev">Slicing</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Reshaping-1"></span><h3 class="section">2.6 Reshaping</h3>

<span id="index-APL"></span>
<span id="index-_002c_002c-ravel"></span>
<span id="index-_005b_003f_005d_002c-reshape"></span>
<p>To match APL ρ, <code>newra</code> offers three separate functions.
</p>
<p><a href="#x_002dra_002dreshape"><code>ra-reshape</code></a> and <a href="#x_002dra_002dravel"><code>ra-ravel</code></a> are in a way the inverse of each other. <code>ra-reshape</code> folds an axis into (potentially) many, while <code>ra-ravel</code> makes a block of axes into a single axis. Neither is able to increase the size of the array (although <code>ra-reshape</code> can <em>reduce</em> it). For that purpose <a href="#x_002dra_002dtile"><code>ra-tile</code></a> is provided.
</p>
<div class="example">
<pre class="verbatim">(ra-dimensions (ra-i 2 3 4))
</pre><pre class="example">&rArr; (2 3 4)
</pre><pre class="verbatim">; insert new axis of size 5 before axis 0
(ra-dimensions (ra-tile (ra-i 2 3 4) 0 5))
</pre><pre class="example">&rArr; (5 2 3 4)
</pre><pre class="verbatim">; collapse axes 0 and 1
(ra-dimensions (ra-ravel (ra-tile (ra-i 2 3 4) 0 5) 2))
</pre><pre class="example">&rArr; (10 3 4)
</pre><pre class="verbatim">; reshape axis 0 into two axes with shape [3 3]
(ra-dimensions (ra-reshape (ra-ravel (ra-tile (ra-i 2 3 4) 0 5) 2) 0 3 3))
</pre><pre class="example">&rArr; (3 3 3 4)
</pre></div>

<p><code>ra-reshape</code> and <code>ra-tile</code> always reuse the root of the argument. On the other hand <code>ra-ravel</code> may not be able to, depending on the storage order of the array — this is one of the reasons to have three different functions instead of only one. You can check in advance whether <code>ra-ravel</code> will reuse the root with the function <a href="#x_002dra_002dorder_002dc_003f"><code>ra-order-c?</code></a>.
</p>
<hr>
</div>
<div class="section" id="Concatenation">
<div class="header">
<p>
Next: <a href="#Transposition" accesskey="n" rel="next">Transposition</a>, Previous: <a href="#Reshaping" accesskey="p" rel="prev">Reshaping</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Concatenation-1"></span><h3 class="section">2.7 Concatenation</h3>

<span id="index-concatenation"></span>
<p><code>newra</code> offers two concatenation operations: <a href="#x_002dra_002dcat"><code>ra-cat</code></a> (prefix cat) and <a href="#x_002dra_002dscat"><code>ra-scat</code></a> (suffix cat).
</p>
<p>For <code>ra-cat</code>, the arguments are prefix-matched, and the concatenation axis is counted from the left. E.g. for three arrays <var>r</var>, <var>s</var>, <var>t</var> with shapes
</p>
<div class="example">
<pre class="verbatim">(r₀ r₁ r₂ r₃)
(s₀ s₁ s₂ s₃ s₄ s₅)
(t₀ t₁)
</pre></div>

<p>Then <code>(define val (ra-cat #t 1 r s t))</code> will prefix-match these to (it is an error if any of <code>r₀=s₀=t₀</code>, <code>r₂=s₂</code>, or <code>r₃=s₃</code> don&rsquo;t hold)
</p>
<div class="example">
<pre class="verbatim">(s₀ |r₁| s₂ s₃ s₄ s₅)
(s₀ |s₁| s₂ s₃ s₄ s₅)
(s₀ |t₁| s₂ s₃ s₄ s₅)
</pre></div>

<p>and then concatenate them along axis 1 into an array of shape <code>(s₀ (r₁+s1+t₁) s₂ s₃ s₄ s₅)</code>.
</p>
<p>For <code>ra-scat</code>, the arguments are suffix-matched, and the concatenation axis is counted from the right. For example
</p>
<div class="example">
<pre class="verbatim">(define r (ra-i 2 3 2))
(define s (list-&gt;ra 1 '(a b)))
(ra-scat #t 1 r s)
</pre></div>

<p>the axes are aligned as
</p>
<div class="example">
<pre class="verbatim">(r₀ r₁ r₂)
      (s₀)
</pre></div>

<p>and suffix-matched (s₀ and r₂ must match)
</p>
<div class="example">
<pre class="verbatim">(r₀ |r₁| r₂)
(r₀ | 1| r₂)
</pre></div>

<p>for a result
</p>
<div class="example">
<pre class="verbatim">(ra-scat #t 1 r s)
</pre><pre class="example">&rArr; <code>#%3(((0 1) (2 3) (4 5) (a b)) ((6 7) (8 9) (10 11) (a b)))</code>
</pre></div>

<p>Note that the rank extension of <code>s</code> on the concatenation axis yields a length of 1 (and not <code>r₀</code>). It can be useful to think of the axis argument of <code>ra-scat</code> as indicating cell rank, so the code above means &lsquo;concatenate 1-cells&rsquo;.
</p>
<p>For both <code>ra-cat</code> and <code>ra-scat</code>, axes other than the concatenation axis must match across all of the arguments.
</p>
<div class="example">
<pre class="verbatim">(ra-cat #t 0 (ra-i 3 2) (ra-i 2))
</pre><pre class="example">&rArr; <code>#%2:4:2((0 1) (2 3) (4 5) (0 0) (1 1))</code>
</pre></div>

<div class="example">
<pre class="verbatim">(ra-scat #t 1 (ra-i 3 2) (ra-i 2))
</pre><pre class="example">&rArr; <code>#%2:4:2((0 1) (2 3) (4 5) (0 1))</code>
</pre></div>

<p>In particular, it is not enough for the lengths to be the same; both bounds must match.
</p>
<div class="example">
<pre class="verbatim">(ra-cat #t 0 (make-ra 'a '(1 1) '(1 4))
             (make-ra 'b '(2 2) '(1 4)))
</pre><pre class="example">&rArr; <code>#%2:2@1:4((a a a a) (b b b b))</code> ; axes 1 match, axes 0 don't need to
</pre></div>

<div class="example">
<pre class="verbatim">(ra-cat #t 1 (make-ra 'a '(1 1) '(1 4))
             (make-ra 'b '(2 2) '(1 4)))
</pre><pre class="example">&rArr; error ; axes 0 don't match
</pre></div>

<p>Here <a href="#x_002dra_002dreshape"><code>ra-reshape</code></a> is used to move axis 0 of the second argument into agreement.<a id="DOCF6" href="#FOOT6"><sup>6</sup></a>
</p>
<div class="example">
<pre class="verbatim">(ra-cat #t 1 (make-ra 'a '(1 1) '(1 4))
             (ra-reshape (make-ra 'b '(2 2) '(1 4)) 0 '(1 1)))
</pre><pre class="example">&rArr; <code>#%2@1:1:8((a a a a b b b b))</code>
</pre></div>

<p>On the concatenation axis, only lengths matter; for both <code>ra-cat</code> and <code>ra-scat</code>, the lower bound is 0 in the result, and the lower bounds of the arguments are ignored.
</p>
<div class="example">
<pre class="verbatim">(define a (make-ra 'a '(1 2) '(2 3)))
(define b (make-ra 'b '(1 2)))
(define c (make-ra 'c '(1 2) '(-1 0)))
(ra-format (ra-cat #t 1 a b c))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2@1:2:5─┐
│a│a│b│c│c│
├─┼─┼─┼─┼─┤
│a│a│b│c│c│
└─┴─┴─┴─┴─┘
</pre></div>

<p>Both <code>ra-cat</code> and <code>ra-scat</code> accept a negative concatenation axis. That will rank-extend all the arguments to the left (<code>ra-cat</code>) or to the right (<code>ra-scat</code>) before concatenating on the leftmost (<code>ra-cat</code>) or rightmost (<code>ra-scat</code>) axis. In the same way, one may give a concatenation axis which is beyond the rank of the argument with the highest rank. Consider
</p>
<div class="example">
<pre class="verbatim">(define abc (list-&gt;ra 1 #(a b c)))
(ra-cat #t -1 (ra-i 3) abc)
</pre><pre class="example">&rArr; <code>#%2:2:3((0 1 2) (a b c))</code>
</pre></div>
<div class="example">
<pre class="verbatim">(ra-cat #t 0 (ra-i 3) abc)
</pre><pre class="example">&rArr; <code>#%1:6(0 1 2 a b c)</code>
</pre></div>
<div class="example">
<pre class="verbatim">(ra-cat #t 1 (ra-i 3) abc)
</pre><pre class="example">&rArr; <code>#%2:3:2((0 a) (1 b) (2 c))</code>
</pre></div>

<p>vs
</p>
<div class="example">
<pre class="verbatim">(ra-scat #t -1 (ra-i 3) abc)
</pre><pre class="example">&rArr; <code>#%2:3:2((0 a) (1 b) (2 c))</code>
</pre></div>
<div class="example">
<pre class="verbatim">(ra-scat #t 0 (ra-i 3) abc)
</pre><pre class="example">&rArr; <code>#%1:6(0 1 2 a b c)</code>
</pre></div>
<div class="example">
<pre class="verbatim">(ra-scat #t 1 (ra-i 3) abc)
</pre><pre class="example">&rArr; <code>#%2:2:3((0 1 2) (a b c))</code>
</pre></div>

<p>Cf J append (,) stitch (,.).
</p>
<hr>
</div>
<div class="section" id="Transposition">
<div class="header">
<p>
Next: <a href="#Other-operations-on-arrays" accesskey="n" rel="next">Other operations on arrays</a>, Previous: <a href="#Concatenation" accesskey="p" rel="prev">Concatenation</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Transposition-1"></span><h3 class="section">2.8 Transposition</h3>

<span id="index-_005b_003f_005d_002c-transpose"></span>
<span id="index-transpose"></span>

<p><a href="#x_002dra_002dtranspose"><code>ra-transpose</code></a> takes a source array and one axis argument for each of the dimensions of the source array. The values of the arguments are the corresponding axes of the result array.
</p>
<div class="example">
<pre class="verbatim">(ra-dimensions (ra-transpose (ra-i 10 20 30) 2 0 1))
</pre><pre class="example">&rArr; <code>'(20 30 10)</code>
</pre></div>

<p>That is, axis 0 in the source array is mapped to axis 2 in the destination array, axis 1 to axis 0, and axis 2 to axis 1. The result array always shares the root of the source array.
</p>
<p>As you&rsquo;d expect
</p>
<div class="example">
<pre class="verbatim">(ra-transpose (ra-i 2 3) 1 0)
</pre><pre class="example">&rArr; <code>#%2d:3:2((0 3) (1 4) (2 5))</code>
</pre></div>

<p>One can map more than one axis of the source array to the same axis of the destination array. In that case the step of the destination axis becomes the sum of the steps of all the source axes. The classic example is
</p>
<span id="index-diagonal"></span>
<div class="example">
<pre class="verbatim">(define A (ra-copy #t (ra-i 3 3)))
(ra-fill! (ra-transpose A 0 0) 'x)
A
</pre><pre class="example">&rArr; <code>#%2:3:3((x 1 2) (3 x 5) (6 7 x))</code>
</pre></div>

<p>If one doesn&rsquo;t give values for all of the source axes, the missing axes are sent beyond the highest one that was given. These are equivalent:
</p>
<div class="example">
<pre class="verbatim">(ra-transpose (ra-i 2 3 4) 1 0 2)
(ra-transpose (ra-i 2 3 4) 1 0) ; fill with (+ 1 (max 1 0))
</pre></div>

<p>as are these:
</p>
<div class="example">
<pre class="verbatim">(ra-transpose (ra-i 2 3) 1) ; fill with (+ 1 (max 1))
(ra-transpose (ra-i 2 3) 1 2)
</pre></div>

<p>Note that in the last example there is no source axis for destination axis 0. Destination axes not mentioned in the axis argument list become <a href="#x_002ddead_002daxes">dead axes</a>. The rank of the result array is always just large enough to fit all the destination axes.
</p>
<div class="example">
<pre class="verbatim">(ra-dimensions (ra-transpose (ra-i 2 3) 1))
</pre><pre class="example">&rArr; (#f 2 3)
</pre></div>

<p>In particular, <code>(ra-transpose A)</code> is equivalent to <code>(ra-transpose A 0 1 ... (- (ra-rank A) 1))</code> (which is of course the same array as <code>A</code>).
</p>
<span id="index-outer-product"></span>
<p>This ability of <code>ra-transpose</code> can be exploited to compute &lsquo;outer products&rsquo;. In the following example the shape <code>[2 2]</code> of <code>A</code> matches with the two leading dead axes of <code>(ra-transpose B 2)</code>:
</p>
<div class="example">
<pre class="verbatim">                 A : [2 2]
(ra-transpose B 2) : [f f 2 2]
</pre></div>

<span id="index-prefix-matching-1"></span>
<p>The trailing axes then match through <a href="#Rank-extension">prefix matching</a>.
</p>
<div class="example">
<pre class="verbatim">(define A (list-&gt;ra 2 '((a b) (c d))))
(define B (ra-i 2 2))
(ra-format (ra-map! (make-ra #f 2 2 2 2)
             (lambda i (format #f &quot;~{~a~}&quot; i))
             A (ra-transpose B 2)))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%4:2:2:2:2═╗
║a0│a1║b0│b1║
║──┼──║──┼──║
║a2│a3║b2│b3║
╠═════╬═════╣
║c0│c1║d0│d1║
║──┼──║──┼──║
║c2│c3║d2│d3║
╚═════╩═════╝
</pre></div>

<span id="index-index-placeholder"></span>
<p>Another use is the creation of ‘index placeholders’, e.g.
</p><div class="example">
<pre class="verbatim">(define (tensor-index i) (ra-transpose (ra-iota) i))
(ra-format (ra-map! (make-ra #f 3 4) list (tensor-index 0) (tensor-index 1)))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2:3:4─────┬─────┬─────┐
│(0 0)│(0 1)│(0 2)│(0 3)│
├─────┼─────┼─────┼─────┤
│(1 0)│(1 1)│(1 2)│(1 3)│
├─────┼─────┼─────┼─────┤
│(2 0)│(2 1)│(2 2)│(2 3)│
└─────┴─────┴─────┴─────┘
</pre></div>

<span id="index-_005b_003f_005d"></span>
<span id="index-grade"></span>
<p>The function <a href="#x_002dra_002duntranspose"><code>ra-untranspose</code></a> takes its axis arguments the other way from <code>ra-transpose</code>; the value of each argument is the axis of the original array and the position in the argument list is the axis of the result array. This is less flexible than <code>ra-transpose</code>, but can be used to reverse an application of <code>ra-transpose</code> without having to sort (‘grade’) the original axis arguments.
</p>
<div class="example">
<pre class="verbatim">(define a (ra-i 2 3 4))
(ra-equal? a (ra-untranspose (ra-transpose a 2 0 1) 2 0 1))
</pre><pre class="example">&rArr; <code>#t</code>
</pre></div>




<hr>
</div>
<div class="section" id="Other-operations-on-arrays">
<div class="header">
<p>
Next: <a href="#Automatic-result-arrays" accesskey="n" rel="next">Automatic result arrays</a>, Previous: <a href="#Transposition" accesskey="p" rel="prev">Transposition</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Other-operations-on-arrays-1"></span><h3 class="section">2.9 Other operations on arrays</h3>

<hr>
</div>
<div class="section" id="Automatic-result-arrays">
<div class="header">
<p>
Next: <a href="#Foreign-interface" accesskey="n" rel="next">Foreign interface</a>, Previous: <a href="#Other-operations-on-arrays" accesskey="p" rel="prev">Other operations on arrays</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Automatic-result-arrays-1"></span><h3 class="section">2.10 Automatic result arrays</h3>

<p>Most of the functions of <code>newra</code> do not create arrays, but instead they expect result arrays to be passed as arguments. This means that they must have been allocated before. However, there are a few functions, such as <a href="#x_002dra_002dcopy"><code>ra-copy</code></a> or <a href="#x_002dra_002dmap"><code>ra-map</code></a>, that do create a result array. The type and shape of that result array is deduced from the source arguments, as follows.
</p>
<ul>
<li> The default type of the result array is the type of the first of the source arguments. If that type is <code>'d</code>, however, the default type of the result array is <code>#t</code>. Usually, a function will allow this default to be overriden with an explicit argument. If that argument is required, then <code>#f</code> will select the default.
</li><li> The rank of the result array will be the rank of the source argument with the largest rank. On each dimension, the lower bound and the length of the result will match those of the source arguments, with the precision that if any of those is finite, then it will be finite in the result as well. (If there is only one source argument, as is the case for <code>ra-copy</code>, then it follows that that is the shape of the result.)
</li></ul>

<p>For example:
</p>
<div class="example">
<pre class="verbatim">(ra-map #t *
  ; shape '((0 1))
  (ra-iota 2 1)
  ; shape '((#f #f) (1 3))
  (ra-transpose (make-ra 9 '(1 3)) 1))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">; shape of result is '((0 1) (1 3))
#%2:2@1:3((9 9 9) (18 18 18)
</pre></div>

<hr>
</div>
<div class="section" id="Foreign-interface">
<div class="header">
<p>
Next: <a href="#Compatibility-with-old-Guile-arrays" accesskey="n" rel="next">Compatibility with old Guile arrays</a>, Previous: <a href="#Automatic-result-arrays" accesskey="p" rel="prev">Automatic result arrays</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Foreign-interface-1"></span><h3 class="section">2.11 Foreign interface</h3>

<p>One of the major reasons to use arrays instead of other Scheme data structures is that they let one pass a large amount of data through a C interface very efficiently. The data doesn&rsquo;t need to be copied — one only needs to pass a pointer to the data, plus the lengths and the steps in some order. C doesn&rsquo;t have a standard consolidated array type, so the particulars are variable. In any case, the required items can be obtained trivially from a <code>newra</code> array object.
</p>
<p>For example:
</p>
<p>TODO
</p>
<hr>
</div>
<div class="section" id="Compatibility-with-old-Guile-arrays">
<div class="header">
<p>
Previous: <a href="#Foreign-interface" accesskey="p" rel="prev">Foreign interface</a>, Up: <a href="#Low-level" accesskey="u" rel="up">Low level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Compatibility-with-old-Guile-arrays-1"></span><h3 class="section">2.12 Compatibility with old Guile arrays</h3>

<p>The functions <a href="#x_002dra_002d_003earray"><code>ra-&gt;array</code></a> and <a href="#x_002darray_002d_003era"><code>array-&gt;ra</code></a> are provided to convert to and from <code>newra</code> arrays and built-in Guile arrays. It is an error to use <code>ra-&gt;array</code> on arrays whose root isn&rsquo;t supported by the built-in arrays, or that have an unbounded axis. Except in those two cases, the conversion is transparent both ways, and the result always shares the root of the argument.
</p>
<div class="example">
<pre class="verbatim">(define a (make-array 'o 2 3))
(define b (array-&gt;ra a))
(ra-set! b 'x 1 1)
(array-set! a 'y 0 2)
a
</pre><pre class="example">&rArr; <code>#2((o o y) (o x o))</code>
</pre><pre class="verbatim">b
</pre><pre class="example">&rArr;  <code>#%2((o o y) (o x o))</code>
</pre></div>

<p><code>&lt;aseq&gt;</code>-root arrays must be type converted before using <code>ra-&gt;array</code>.
</p>
<div class="example">
<pre class="verbatim">(ra-&gt;array (ra-copy #t (ra-i 2 3)))
</pre><pre class="example">&rArr; #2((0 1 2) (3 4 5))
</pre></div>

<p>On dead axes, lengths can be set to 1 (with <a href="#x_002dra_002dsingletonize"><code>ra-singletonize</code></a>) to allow conversion with <code>ra-&gt;array</code> or to other array systems that do singleton broadcasting.
</p>
<div class="example">
<pre class="verbatim">(define a (ra-transpose (ra-i 2 3) 1 3))
a
</pre><pre class="example">&rArr; <code>#%4d:d:2:d:3((((0 1 2)) ((3 4 5))))</code>
</pre><pre class="verbatim">(ra-singletonize a)
</pre><pre class="example">&rArr; <code>#%4d:1:2:1:3((((0 1 2)) ((3 4 5))))</code>
</pre></div>

<p>One important difference between the built-in array functions and <code>newra</code> is that bounds matching in <code>newra</code> is strict: finite bounds must be identical for axes to match, while for <code>array-map!</code>, <code>array-for-each</code>, <code>array-copy!</code>, etc. the iteration range is the intersection of the ranges of the arguments<a id="DOCF7" href="#FOOT7"><sup>7</sup></a>. <code>newra</code> provides <a href="#x_002dra_002dclip"><code>ra-clip</code></a> to match ranges easily.
</p>
<div class="example">
<pre class="verbatim">(define a (make-ra-root (vector 'a 'b 'c 'd 'e 'f 'g))) ; range is 0..6
(define b (ra-reshape (ra-iota 4) 0 '(2 5))) ; range is 2..5
(ra-copy! a b)
</pre><pre class="example">&rArr; <code>Throw to key `mismatched-lens' with args `(7 4 at-dim 0)'.</code>
</pre><pre class="verbatim">(ra-copy! (ra-clip a b) b)
a
</pre><pre class="example">&rArr; <code>#%1:7(a b 0 1 2 3 g)</code>
</pre></div>

<hr>
</div>
</div>
<div class="chapter" id="High-level">
<div class="header">
<p>
Next: <a href="#Hazards" accesskey="n" rel="next">Hazards</a>, Previous: <a href="#Low-level" accesskey="p" rel="prev">Low level</a>, Up: <a href="#Top" accesskey="u" rel="up"><code>newra</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="High-level-1"></span><h2 class="chapter">3 High level</h2>

<p>NOTE This section is about a facility that hasn&rsquo;t been implemented yet.
</p>
<p>In array languages such as APL, scalar operations are implicitly extended to work on arrays, so one can just write (the equivalent of) <code>(+ A B)</code> instead of <code>(ra-map! (make-ra ...) + A B)</code>. The basic <code>newra</code> iteration operations such as <code>ra-map!</code> already perform rank extension of their arguments (so <code>A</code> or <code>B</code> can have a different rank from the result, as long as the prefix axes match). We still need ways to:
</p>
<ul>
<li> associate an operation to the ranks of their arguments, so that the right frame of iteration can be chosen.
</li><li> compute the shape and type of the result (if any).
</li><li> handle scalar (non-array) arguments.
</li></ul>


<ul class="section-toc">
<li><a href="#Verbs" accesskey="1">Verbs</a></li>
<li><a href="#Reductions" accesskey="2">Reductions</a></li>
</ul>
<hr>
<div class="section" id="Verbs">
<div class="header">
<p>
Next: <a href="#Reductions" accesskey="n" rel="next">Reductions</a>, Up: <a href="#High-level" accesskey="u" rel="up">High level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Verbs-1"></span><h3 class="section">3.1 Verbs</h3>

<hr>
</div>
<div class="section" id="Reductions">
<div class="header">
<p>
Previous: <a href="#Verbs" accesskey="p" rel="prev">Verbs</a>, Up: <a href="#High-level" accesskey="u" rel="up">High level</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Reductions-1"></span><h3 class="section">3.2 Reductions</h3>

<hr>
</div>
</div>
<div class="chapter" id="Hazards">
<div class="header">
<p>
Next: <a href="#Reference" accesskey="n" rel="next">Reference</a>, Previous: <a href="#High-level" accesskey="p" rel="prev">High level</a>, Up: <a href="#Top" accesskey="u" rel="up"><code>newra</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Hazards-1"></span><h2 class="chapter">4 Hazards</h2>


<ul class="section-toc">
<li><a href="#Differences-with_002e_002e_002e" accesskey="1">Differences with...</a></li>
<li><a href="#Common-mistakes" accesskey="2">Common mistakes</a></li>
<li><a href="#Performance-pitfalls" accesskey="3">Performance pitfalls</a></li>
</ul>
<hr>
<div class="section" id="Differences-with_002e_002e_002e">
<div class="header">
<p>
Next: <a href="#Common-mistakes" accesskey="n" rel="next">Common mistakes</a>, Up: <a href="#Hazards" accesskey="u" rel="up">Hazards</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Differences-with_002e_002e_002e-1"></span><h3 class="section">4.1 Differences with...</h3>

<p>If you come to <code>newra</code> from another array language or library, you may want to be aware of some of these differences. See also the <a href="#Cheatsheet">Cheatsheet</a>.
</p>
<p>Differences with built-in Guile arrays:
</p><ul>
<li> <code>newra</code> map operations are rank-extending but require exact agreement of bounds, unlike operations on built-in arrays, which require exact rank agreement but admit overlapping bounds.
</li></ul>

<span id="index-APL-1"></span>
<p>Differences with APL:
</p><ul>
<li> The default lower bound (base index) in <code>newra</code> is 0, as in <code>⎕io←0</code>. The lower bound isn&rsquo;t global, but it may be different per axis.
</li><li> <code>newra</code> arrays of size 1 are not equivalent to scalars and always retain their rank. For example, <code>(make-ra 99)</code>, <code>(make-ra 99 1)</code> and <code>(make-ra 99 1 1)</code> are all different from each other and from the scalar <code>99</code>, while in APL <code>99</code>, <code>(1 ⍴ 99)</code>, and <code>(1 1 ⍴ 99)</code> are all the same thing.
</li><li> When a function takes multiple arguments, the meaning with multiple arguments is an extension of the meaning with a single argument. This contrasts with APL where the monadic and dyadic versions of a verb usually have a related but independent definition. For example <code>(ra-transpose a)</code>≡<code>(ra-transpose a 0)</code>≡<code>(ra-transpose a 0 1)</code>, but (assuming <code>a</code> is of rank 2) <code>⍉a</code>≡<code>2 1⍉a</code>. Please check the documentation for each function.
</li></ul>

<span id="index-Fortran"></span>
<p>Differences with Fortran:
</p><ul>
<li> The default lower bound (base index) in <code>newra</code> is 0, not 1. Like in Fortran, the lower bound may be different for each axis of each array.
</li><li> Unlike Fortran, the default element order in arrays is row-major, or ‘last index changes fastest’. It&rsquo;s possible to define and manipulate arrays in any other order, including Fortran&rsquo;s default. However, some functions (such as <code>ra-ravel</code>) only support row-major order.
</li><li> <code>newra</code> uses prefix matching for rank extension on arguments on any rank, while Fortran only performs rank extension on scalar arguments.
</li></ul>

<span id="index-Python"></span>
<span id="index-NumPy"></span>
<p>Differences with NumPy:
</p><ul>
<li> <code>newra</code> uses prefix matching for rank extension, while Numpy uses suffix matching. For example: FIXME.
</li><li> <code>newra</code> doesn&rsquo;t use singleton broadcasting. Axes of length 1 only match axes of length 1. For example, <code>(ra-map! (make-ra 0 2) + (make-ra 90 1) (make-ra 7 2))</code> is an error because the shapes (2), (1), (2) don&rsquo;t agree.
</li></ul>

<span id="index-Octave"></span>
<span id="index-Matlab"></span>
<p>Differences with Octave:
</p><ul>
<li> The default lower bound (base index) in <code>newra</code> is 0, not 1. Lower bounds may be 1 on a particular array (or particular axes of an array), but not globally.
</li><li> In Octave, any array of rank ≤ 2 is implicity a matrix (an array of rank 2). This isn&rsquo;t true in <code>newra</code>, so, for example, an array of rank 1 isn&rsquo;t equivalent to an array of rank 2 with a single row (a ‘row vector’).
</li><li> Unlike Octave, the default element order in arrays is row-major, or ‘last index changes fastest’. It&rsquo;s possible to define and manipulate arrays in any other order, including Octave&rsquo;s default. However, some functions (such as <code>ra-ravel</code>) only support row-major order.
</li><li> <code>newra</code> uses prefix matching for rank extension on arguments on any rank, while Octave only performs rank extension on scalar arguments.
</li></ul>

<hr>
</div>
<div class="section" id="Common-mistakes">
<div class="header">
<p>
Next: <a href="#Performance-pitfalls" accesskey="n" rel="next">Performance pitfalls</a>, Previous: <a href="#Differences-with_002e_002e_002e" accesskey="p" rel="prev">Differences with...</a>, Up: <a href="#Hazards" accesskey="u" rel="up">Hazards</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Common-mistakes-1"></span><h3 class="section">4.2 Common mistakes</h3>

<hr>
</div>
<div class="section" id="Performance-pitfalls">
<div class="header">
<p>
Previous: <a href="#Common-mistakes" accesskey="p" rel="prev">Common mistakes</a>, Up: <a href="#Hazards" accesskey="u" rel="up">Hazards</a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Performance-pitfalls-1"></span><h3 class="section">4.3 Performance pitfalls</h3>

<hr>
</div>
</div>
<div class="chapter" id="Reference">
<div class="header">
<p>
Next: <a href="#Cheatsheet" accesskey="n" rel="next">Cheatsheet</a>, Previous: <a href="#Hazards" accesskey="p" rel="prev">Hazards</a>, Up: <a href="#Top" accesskey="u" rel="up"><code>newra</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Reference-1"></span><h2 class="chapter">5 Reference</h2>

<span id="index-array_002d_003era"></span>
<span id="x_002darray_002d_003era"></span><dl class="def">
<dt id="index-array_002d_003era-1"><span class="category">Function<!-- /@w -->: </span><span><strong>array-&gt;ra</strong> <em>a</em><a href='#index-array_002d_003era-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Convert built-in Guile array <var>a</var> (anything that satisfies <code>array?</code>) into a (<code>newra)</code> array.
</p>
<p>This function doesn&rsquo;t create a copy of the array, but reuses the root (<code>shared-array-root</code>) of <var>a</var>, that is, <code>(eq? (ra-root (array-&gt;ra a)) (shared-array-root a))</code> is <code>#t</code>.
</p>
<div class="example">
<pre class="verbatim">(define a (make-array 'x 2 2))
(define b (array-&gt;ra v))
b
</pre><pre class="example">&rArr; <code>#%2:2:2((x x) (x x))</code>
</pre><pre class="verbatim">(ra-fill! b 'y)
a
</pre><pre class="example">&rArr; <code>#2((y y) (y y))</code>
</pre></div>

<p>See also: <a href="#x_002dra_002d_003earray"><code>ra-&gt;array</code></a>.
</p>
</dd></dl>

<span id="index-c_002ddims"></span>
<span id="x_002dc_002ddims"></span><dl class="def">
<dt id="index-c_002ddims-1"><span class="category">Function<!-- /@w -->: </span><span><strong>c-dims</strong> <em>bounds ...</em><a href='#index-c_002ddims-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<span id="index-packed-array"></span>
<p>Create dims for row-major order array (packed elements, last dimension changing fastest).
</p>
<p>Each of the bounds may be a pair of bounds (<var>lo</var> <var>hi</var>) or a single length <var>len</var>, which implies zero <var>lo</var>.
</p><div class="example">
<pre class="verbatim">(c-dims 2 3)
</pre><pre class="example">&rArr; <code>#(#&lt;&lt;dim&gt; len: 2 lo: 0 step: 3&gt; #&lt;&lt;dim&gt; len: 3 lo: 0 step: 1&gt;)</code>
</pre></div>
</dd></dl>

<span id="index-ldots-1"></span>
<span id="x_002dldots"></span><dl class="def">
<dt id="index-ldots-2"><span class="category">Function<!-- /@w -->: </span><span><strong>ldots</strong> <em>[n] ...</em><a href='#index-ldots-2' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Placeholder for <var>n</var> full axes, used as argument to <code>ra-from</code> or <code>ra-amend!</code>. Without <var>n</var>, expand to fill the rank of the argument <var>a</var> of <a href="#x_002dra_002dfrom"><code>ra-from</code></a> or <a href="#x_002dra_002damend_0021"><code>ra-amend!</code></a>.
</p></dd></dl>

<span id="index-make_002dra"></span>
<span id="x_002dmake_002dra"></span><dl class="def">
<dt id="index-make_002dra-1"><span class="category">Function<!-- /@w -->: </span><span><strong>make-ra</strong> <em>val bounds ... &rArr; a</em><a href='#index-make_002dra-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Create an array of type <code>#t</code> with the given <var>bounds</var>, filled with <var>val</var>.
</p>
<div class="example">
<pre class="verbatim">(make-ra 0 '(2 3) 4)
</pre><pre class="example">&rArr; <code>#%2@2:2:4((0 0 0 0) (0 0 0 0))</code>
</pre></div>

<p>See also: <a href="#x_002dmake_002dtyped_002dra"><code>make-typed-ra</code></a>, <a href="#x_002dmake_002dra_002dnew"><code>ra-make-ra-new</code></a>, <a href="#x_002dra_002dshape"><code>ra-shape</code></a>.
</p>
</dd></dl>

<span id="index-make_002dra_002dnew"></span>
<span id="x_002dmake_002dra_002dnew"></span><dl class="def">
<dt id="index-make_002dra_002dnew-1"><span class="category">Function<!-- /@w -->: </span><span><strong>make-ra-new</strong> <em>type value dims</em><a href='#index-make_002dra_002dnew-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Create an array over a new root of the given <var>type</var> and size (according to <var>dims</var>), and fill it with <var>value</var>.
</p><div class="example">
<pre class="verbatim">(make-ra-new 'u8 0 (c-dims 3 2))
</pre><pre class="example">&rArr; #%2u8:3:2((0 0) (0 0) (0 0))
</pre></div>
</dd></dl>

<span id="index-make_002dra_002droot"></span>
<span id="x_002dmake_002dra_002droot"></span><dl class="def">
<dt id="index-make_002dra_002droot-1"><span class="category">Function<!-- /@w -->: </span><span><strong>make-ra-root</strong> <em>root [dims [zero]]</em><a href='#index-make_002dra_002droot-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Create an array over the given <var>root</var>.
</p><div class="example">
<pre class="verbatim">(make-ra-root (vector 1 2 3))
</pre><pre class="example">&rArr; #%1d:3(1 2 3)
</pre></div>

<div class="example">
<pre class="verbatim">(make-ra-root (vector 1 2 3) (vector (make-dim 2)))
</pre><pre class="example">&rArr; #%1d:2(1 2)
</pre></div>

<div class="example">
<pre class="verbatim">(make-ra-root (vector 1 2 3) (vector (make-dim 2)) 1)
</pre><pre class="example">&rArr; #%1d:2(2 3)
</pre></div>
</dd></dl>

<span id="index-make_002dtyped_002dra"></span>
<span id="x_002dmake_002dtyped_002dra"></span><dl class="def">
<dt id="index-make_002dtyped_002dra-1"><span class="category">Function<!-- /@w -->: </span><span><strong>make-typed-ra</strong> <em>type val bounds ... &rArr; a</em><a href='#index-make_002dtyped_002dra-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Same as <a href="#x_002dmake_002dra"><code>make-ra</code></a>, except that the result has the specified <var>type</var>.
</p>
<p>See also: <a href="#x_002dmake_002dra"><code>make-ra</code></a>, <a href="#x_002dmake_002dra_002droot"><code>ra-make-ra-root</code></a>.
</p>
</dd></dl>

<span id="index-intersection"></span>
<span id="index-ra_002dclip"></span>
<span id="x_002dra_002dclip"></span><dl class="def">
<dt id="index-ra_002dclip-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-clip</strong> <em>a b &rArr; c</em><a href='#index-ra_002dclip-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Slice <var>a</var> to the intersection of the bounds of <var>a</var> and <var>b</var>. If <var>a</var> and <var>b</var> have different ranks, only the common prefix of <var>a</var> is sliced.
</p>
<div class="example">
<pre class="verbatim">(define f (make-ra &quot;   &quot; '(-4 4) '(-5 3)))
(define a (make-ra &quot; A &quot; '(-3 0) '(-4 1)))
(define b (make-ra &quot; B &quot; '(-1 3) '(-1 2)))
(ra-fill! (ra-clip a b) &quot; x &quot;)
(ra-copy! (ra-clip f b) (ra-clip b f))
(ra-copy! (ra-clip f a) (ra-clip a f))
(ra-format f)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2@-4:9@-5:9───┬───┬───┬───┬───┬───┐
│   │   │   │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ A │ A │ A │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ A │ A │ A │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ x │ x │ x │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ x │ x │ x │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │   │   │
└───┴───┴───┴───┴───┴───┴───┴───┴───┘
</pre><pre class="verbatim">(ra-fill! (ra-clip f (ra-clip a b)) &quot; o &quot;)
(ra-format f)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2@-4:9@-5:9───┬───┬───┬───┬───┬───┐
│   │   │   │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ A │ A │ A │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ A │ A │ A │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ o │ o │ o │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ o │ o │ o │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │   │   │
└───┴───┴───┴───┴───┴───┴───┴───┴───┘
</pre></div>

<p>The result of <code>ra-clip</code> always shares the root of its first argument <var>a</var>.
</p>
<p>See also: <a href="#Slicing">Slicing</a>, <a href="#Compatibility-with-old-Guile-arrays">Compatibility with old Guile arrays</a>.
</p></dd></dl>

<span id="index-ra_002ddimensions"></span>
<span id="x_002dra_002ddimensions"></span><dl class="def">
<dt id="index-ra_002ddimensions-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-dimensions</strong> <em>a</em><a href='#index-ra_002ddimensions-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Return the dimensions of <var>a</var> as a list, like <a href="#x_002dra_002dshape"><code>ra-shape</code></a>, but the dimensions that have lower bound zero are represented by their length alone, instead of a two-element list <code>(lo hi)</code>. This is a convenience for the common case when lower bounds are zero.
</p>
<div class="example">
<pre class="verbatim">(ra-dimensions (make-ra 0 '(2 3) 4))
</pre><pre class="example">&rArr; <code>((2 3) 4)</code>
</pre><pre class="verbatim">(ra-shape (make-ra 0 '(2 3) 4))
</pre><pre class="example">&rArr; <code>((2 3) (0 3))</code>
</pre></div>

<p>See also: <a href="#x_002dra_002dshape"><code>ra-shape</code></a>, <a href="#x_002dmake_002dra"><code>make-ra</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dformat"></span>
<span id="x_002dra_002dformat"></span><dl class="def">
<dt id="index-ra_002dformat-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-format</strong> <em>ra port #:fmt #:prefix?</em><a href='#index-ra_002dformat-1' class='copiable-anchor'> &para;</a></span></dt>
<dt id="index-ra_002dformat-2"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-format</strong> <em>ra #f #:fmt #:prefix? &rArr; sc</em><a href='#index-ra_002dformat-2' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Pretty print array <var>ra</var>.
</p>
<p>Each element <var>x</var> of <var>ra</var> is converted to a string using <code>(fmt x)</code>, or <code>(format #f fmt x)</code><a id="DOCF8" href="#FOOT8"><sup>8</sup></a> if <var>fmt</var> is a string. <var>fmt</var> defauts to <code>&quot;~a&quot;</code>. Elements that are arrays are formatted using <code>ra-format</code> recursively.
</p>
<p>If <var>port</var> is <code>#f</code>, nothing is printed; instead, the function returns a rank-2 character array <var>sc</var> with the result of the printing. Otherwise the array is printed to <var>port</var> and the function returns unspecified values. The default for <var>port</var> is <code>#t</code>, which works as <code>current-output-port</code>.
</p>
<p>If <var>prefix?</var> is true, the array print prefix <a href="#x_002dra_002dprint_002dprefix"><code>ra-print-prefix</code></a> is printed over the first line of the printout if the rank of <var>ra</var> is 2 or greater, else it is printed on a separate line above the printout.
</p>
<p>If <var>compact?</var> is true, the separators for the rank-0 cells are replaced by spaces and the separators for the rank-1 cells are omitted. This results in a more compact output at the cost of some clarity.
</p>
<p>This function handles arrays of rank up to 8, or up to 10 in compact mode. The even dimensions (counting from the last one) are arranged horizontally, while the odd dimensions are arranged vertically. The dimensions are separated visually using <a href="https://unicode.org/charts/nameslist/n_2500.html">box-drawing characters</a>. This might look better or worse depending on the font.
</p>
<p>A 0-array:
</p><div class="example">
<pre class="verbatim">(ra-format (make-ra 'element))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%0
element
</pre></div>

<p>A 1-array:
</p><div class="example">
<pre class="verbatim">(ra-format (ra-i 4))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%1d:4
│0│1│2│3│
</pre></div>

<p>Compare with the 2-array
</p><div class="example">
<pre class="verbatim">(ra-format (ra-i 1 4))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2d:1:4┐
│0│1│2│3│
└─┴─┴─┴─┘
</pre></div>

<p>Another 2-array:
</p><div class="example">
<pre class="verbatim">(ra-format (ra-i 3 4) #:prefix? #f)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">┌─┬─┬──┬──┐
│0│1│ 2│ 3│
├─┼─┼──┼──┤
│4│5│ 6│ 7│
├─┼─┼──┼──┤
│8│9│10│11│
└─┴─┴──┴──┘
</pre></div>

<p>A 5-array:
</p><div class="example">
<pre class="verbatim">(ra-format (ra-i 2 2 3 2 4) #:prefix? #f)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">┃═══════════╦═══════════╦═══════════┃═══════════╦═══════════╦═══════════┃
┃ 0│ 1│ 2│ 3║ 8│ 9│10│11║16│17│18│19┃48│49│50│51║56│57│58│59║64│65│66│67┃
┃──┼──┼──┼──║──┼──┼──┼──║──┼──┼──┼──┃──┼──┼──┼──║──┼──┼──┼──║──┼──┼──┼──┃
┃ 4│ 5│ 6│ 7║12│13│14│15║20│21│22│23┃52│53│54│55║60│61│62│63║68│69│70│71┃
┃═══════════╬═══════════╬═══════════┃═══════════╬═══════════╬═══════════┃
┃24│25│26│27║32│33│34│35║40│41│42│43┃72│73│74│75║80│81│82│83║88│89│90│91┃
┃──┼──┼──┼──║──┼──┼──┼──║──┼──┼──┼──┃──┼──┼──┼──║──┼──┼──┼──║──┼──┼──┼──┃
┃28│29│30│31║36│37│38│39║44│45│46│47┃76│77│78│79║84│85│86│87║92│93│94│95┃
┃═══════════╩═══════════╩═══════════┃═══════════╩═══════════╩═══════════┃
</pre></div>

<p>The same 5-array in compact mode:
</p><div class="example">
<pre class="verbatim">(ra-format (ra-i 2 2 3 2 4) #:prefix? #f #:compact? #t)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">║───────────┬───────────┬───────────║───────────┬───────────┬───────────║
║ 0  1  2  3│ 8  9 10 11│16 17 18 19║48 49 50 51│56 57 58 59│64 65 66 67║
║ 4  5  6  7│12 13 14 15│20 21 22 23║52 53 54 55│60 61 62 63│68 69 70 71║
║───────────┼───────────┼───────────║───────────┼───────────┼───────────║
║24 25 26 27│32 33 34 35│40 41 42 43║72 73 74 75│80 81 82 83│88 89 90 91║
║28 29 30 31│36 37 38 39│44 45 46 47║76 77 78 79│84 85 86 87│92 93 94 95║
║───────────┴───────────┴───────────║───────────┴───────────┴───────────║
</pre></div>

<span id="index-SRFI_002d163-1"></span>
<p>A nested array (example from [<a href="#Sources">SRFI-163</a>]
):
</p>
<div class="example">
<pre class="verbatim">(ra-format (call-with-input-string &quot;#%2@1:2@1:3((#%2((1 2) (3 4)) 9 #%2((3 4) (5 6)))
                                    (#%(42 43) #%2((8 7 6)) #%2((90 91) (100 101))))))&quot;
                                   read))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2@1:2@1:3─────┬─────────┐
│#%2:2:2│      9│  #%2:2:2│
││1│2│  │       │  │3│4│  │
│├─┼─┤  │       │  ├─┼─┤  │
││3│4│  │       │  │5│6│  │
│└─┴─┘  │       │  └─┴─┘  │
├───────┼───────┼─────────┤
│#%1:2  │#%2:1:3│#%2:2:2─┐│
││42│43│││8│7│6│││ 90│ 91││
│       │└─┴─┴─┘│├───┼───┤│
│       │       ││100│101││
│       │       │└───┴───┘│
└───────┴───────┴─────────┘
</pre></div>

<p>Looking at the return value when <var>port</var> is <code>#f</code>:
</p><div class="example">
<pre class="verbatim">(ra-format (ra-format (ra-i 2 3) #f #:prefix? #f) #:prefix? #f)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">┌─┬─┬─┬─┬─┬─┬─┐
│┌│─│┬│─│┬│─│┐│
├─┼─┼─┼─┼─┼─┼─┤
│││0│││1│││2│││
├─┼─┼─┼─┼─┼─┼─┤
│├│─│┼│─│┼│─│┤│
├─┼─┼─┼─┼─┼─┼─┤
│││3│││4│││5│││
├─┼─┼─┼─┼─┼─┼─┤
│└│─│┴│─│┴│─│┘│
└─┴─┴─┴─┴─┴─┴─┘
</pre></div>

<p>Using a custom element formatter:
</p><div class="example">
<pre class="verbatim">(ra-format (ra-map! (make-ra #f 4 4) sqrt (ra-reshape (ra-iota 20 -10) 0 4 4))
           #:fmt (lambda (x) (format #f (cond ((real? x) &quot;~4,2f&quot;)
                                              ((complex? x) &quot;~4,2i&quot;)
                                              (else &quot;~a&quot;))
                                     x)))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2:4:4────┬──────────┬──────────┬──────────┐
│0.00+3.16i│0.00+3.00i│0.00+2.83i│0.00+2.65i│
├──────────┼──────────┼──────────┼──────────┤
│0.00+2.45i│0.00+2.24i│0.00+2.00i│0.00+1.73i│
├──────────┼──────────┼──────────┼──────────┤
│0.00+1.41i│0.00+1.00i│      0.00│      1.00│
├──────────┼──────────┼──────────┼──────────┤
│      1.41│      1.73│      2.00│      2.24│
└──────────┴──────────┴──────────┴──────────┘
</pre></div>

<p>If any of the lengths of <var>ra</var> is 0, only the prefix is printed.
</p>
<p>This function doesn&rsquo;t handle large arrays in any particular way. User beware!
</p>
<p>See also: <a href="#x_002dra_002dprint"><code>ra-print</code></a>, <a href="#x_002dstar_002dra_002dprint_002dstar"><code>*ra-print*</code></a>.
</p>
</dd></dl>

<span id="index-ra_002di"></span>
<span id="x_002dra_002di"></span><dl class="def">
<dt id="index-ra_002di-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-i</strong> <em>bounds ...</em><a href='#index-ra_002di-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Create multidimensional index array with the given bounds.
</p>
<p>The root is of type <code>d</code>. The first upper bound that isn&rsquo;t <code>#f</code> may be <code>#t</code>; this creates an unbounded axis.
</p>
<div class="example">
<pre class="verbatim">(ra-i 2 3 4)
</pre><pre class="example">&rArr; #%3d:2:3:4(((0 1 2 3) (4 5 6 7) (8 9 10 11)) ((12 13 14 15) (16 17 18 19) (20 21 22 23)))
</pre></div>

<p>See also: <a href="#x_002dra_002diota"><code>ra-iota</code></a>, <a href="#x_002dra_002dindex_002dmap_0021"><code>ra-index-map!</code></a>. <a id="DOCF9" href="#FOOT9"><sup>9</sup></a>
</p>
</dd></dl>

<span id="index-ra_002diota"></span>
<span id="x_002dra_002diota"></span><dl class="def">
<dt id="index-ra_002diota-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-iota</strong> <em>len [lo [step]]</em><a href='#index-ra_002diota-1' class='copiable-anchor'> &para;</a></span></dt>
<dt id="index-ra_002diota-2"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-iota</strong><a href='#index-ra_002diota-2' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Create rank-1 index array. The root is of type <code>d</code>. <var>lo</var> defaults to 0 and <var>step</var> to 1.
</p>
<div class="example">
<pre class="verbatim">(ra-iota 4 3 -1)
</pre><pre class="example">&rArr; #%1d:4(3 2 1 0)
</pre></div>

<p><code>(ra-iota)</code> is unbounded both ways, e.g.
</p>
<div class="example">
<pre class="verbatim">(ra-shape (ra-iota))
</pre><pre class="example">&rArr; <code>((#f #f))</code>
</pre><pre class="verbatim">((ra-iota) -100000000000)
</pre><pre class="example">&rArr; -100000000000
</pre></div>

<p>See also: <a href="#x_002dra_002di"><code>ra-i</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dcat"></span>
<span id="x_002dra_002dcat"></span><dl class="def">
<dt id="index-ra_002dcat-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-cat</strong> <em>type i a ...  &rArr; b</em><a href='#index-ra_002dcat-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Concatenate arrays <var>a</var> ... along axis <var>i</var>. The arguments are prefix-matched and rank extended before concatenation. All axes must match, other than the concatenation axis.
</p>
<p>This function always produces a new array, of the type given. If <var>type</var> is <code>#f</code> then the type of the first <var>a</var> is used, unless that is <code>d</code>, in which case <code>#t</code> is used. The lower bound in the concatenation axis of the result is 0; the lower bounds of the arguments in the concatenation axis are ignored.
</p>
<div class="example">
<pre class="verbatim">(ra-cat #f 1 #%1(a b) #%2((0 1) (2 3)))
</pre><pre class="example">&rArr; #%2((a 0 1) (b 2 3))
</pre></div>

<p>See also: <a href="#x_002dra_002dscat"><code>ra-scat</code></a>, <a href="#x_002dra_002dtile"><code>ra-tile</code></a>,  <a href="#Concatenation">Concatenation</a>.
</p>
</dd></dl>

<span id="index-ra_002dprint"></span>
<span id="x_002dra_002dprint"></span><dl class="def">
<dt id="index-ra_002dprint-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-print</strong> <em>ra [port]</em><a href='#index-ra_002dprint-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Print an array to <var>port</var>. <var>port</var> defaults to <code>(current-output-port)</code>.
</p>
<p>This is the default array printer. The result is meant to be back-readable, although some special arrays are not supported yet.
</p>
<p>See also: <a href="#x_002dra_002dformat"><code>ra-format</code></a>, <a href="#x_002dstar_002dra_002dprint_002dstar"><code>*ra-print*</code></a>, <a href="#x_002dstar_002dra_002dparenthesized_002drank_002dzero_002dstar"><code>*ra-parenthesized-rank-zero*</code></a>.
</p></dd></dl>


<span id="index-print-prefix"></span>
<span id="index-ra_002dprint_002dprefix"></span>
<span id="x_002dra_002dprint_002dprefix"></span><dl class="def">
<dt id="index-ra_002dprint_002dprefix-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-print-prefix</strong> <em>ra port #:dims?</em><a href='#index-ra_002dprint_002dprefix-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Return the print prefix for array <var>ra</var>. This is a string that details the type, rank, and (optionally) the dimensions of <var>ra</var>, and is part of the default read syntax for arrays. This is the same syntax as that of the <a href="https://www.gnu.org/software/guile/manual/html_node/Array-Syntax.html">the built in Guile arrays</a>, except that <var>dims?</var> defaults to true and <code>#%</code> is used instead of <code>#</code>.
</p>
<p>This function is provided by the module <code>(newra print)</code>.
</p>
<div class="example">
<pre class="verbatim">(call-with-output-string (cut ra-print-prefix (make-ra 4 '(3 4) '(2 3)) &lt;&gt;))
</pre><pre class="example">&rArr; <code>&quot;#%2@3:2@2:2&quot;</code>
</pre></div>

<div class="example">
<pre class="verbatim">(call-with-output-string (cut ra-print-prefix (make-ra 4 '(3 4) '(2 3)) &lt;&gt; #:dims? #t))
</pre><pre class="example">&rArr; <code>&quot;#%2@3@2&quot;</code>
</pre></div>

<p>See also: <a href="#x_002dra_002dformat"><code>ra-format</code></a>, <a href="#Writing-and-reading">Writing and reading</a>.
</p>
</dd></dl>

<span id="index-ra_002dravel"></span>
<span id="x_002dra_002dravel"></span><dl class="def">
<dt id="index-ra_002dravel-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-ravel</strong> <em>a [n [org]] &rArr; b</em><a href='#index-ra_002dravel-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Ravel axes [<var>org</var> ... <var>org</var>+<var>n</var>) of array <var>a</var> in row-major order. <var>n</var> defaults to the rank of <var>a</var> and <var>org</var> defaults to 0.
</p>
<p>For example:
</p><div class="example">
<pre class="verbatim">(ra-ravel (ra-i 2 3))
</pre><pre class="example">&rArr; #%1d:6(0 1 2 3 4 5)
</pre></div>

<p>Consider this 3-array:
</p>
<div class="example">
<pre class="verbatim">(ra-format (ra-i 2 3 4))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%3d:2:3:4║──┬──┬──┬──║
║0│1│ 2│ 3║12│13│14│15║
║─┼─┼──┼──║──┼──┼──┼──║
║4│5│ 6│ 7║16│17│18│19║
║─┼─┼──┼──║──┼──┼──┼──║
║8│9│10│11║20│21│22│23║
║─┴─┴──┴──║──┴──┴──┴──║
</pre></div>

<p>Ravel axes 0..1:
</p>
<div class="example">
<pre class="verbatim">(ra-format (ra-ravel (ra-i 2 3 4) 2)) ; or (ra-ravel ... 2 0)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2d:6:4─┬──┐
│ 0│ 1│ 2│ 3│
├──┼──┼──┼──┤
│ 4│ 5│ 6│ 7│
├──┼──┼──┼──┤
│ 8│ 9│10│11│
├──┼──┼──┼──┤
│12│13│14│15│
├──┼──┼──┼──┤
│16│17│18│19│
├──┼──┼──┼──┤
│20│21│22│23│
└──┴──┴──┴──┘
</pre></div>

<p>Ravel axes 1..2:
</p>
<div class="example">
<pre class="verbatim">(ra-format (ra-ravel (ra-i 2 3 4) 2 1))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim"></pre><pre class="example">#%2d:2:12┬──┬──┬──┬──┬──┬──┬──┬──┬──┐
│ 0│ 1│ 2│ 3│ 4│ 5│ 6│ 7│ 8│ 9│10│11│
├──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┤
│12│13│14│15│16│17│18│19│20│21│22│23│
└──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘
</pre></div>

<p>To ravel other combinations of axes, use <a href="#Transposition">Transposition</a>.
</p>
<span id="index-packed-array-1"></span>
<p>The full ravel of an array doesn&rsquo;t necessarily result in a rank-1 &lsquo;packed&rsquo; array, that is, one where the step is 1. If that is required, one can use <code>(ra-ravel (ra-copy ra))</code>. <a id="DOCF10" href="#FOOT10"><sup>10</sup></a>.
</p>
<p>See also: <a href="#x_002dra_002dreshape"><code>ra-reshape</code></a>, <a href="#x_002dra_002dtile"><code>ra-tile</code></a>, <a href="#Reshaping">Reshaping</a>.
</p>
</dd></dl>

<span id="index-ra_002dreshape"></span>
<span id="x_002dra_002dreshape"></span><dl class="def">
<dt id="index-ra_002dreshape-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-reshape</strong> <em>a k bounds ... &rArr; b</em><a href='#index-ra_002dreshape-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Reshape axis <var>k</var> of array <var>a</var> to <var>bounds</var>.
</p>
<p>Each of the bounds may be an integer (a length) or a pair of integers (lower and upper bounds).
</p><div class="example">
<pre class="verbatim">(define a (ra-i 4 3))
(ra-format a)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2d:4:3┐
│0│ 1│ 2│
├─┼──┼──┤
│3│ 4│ 5│
├─┼──┼──┤
│6│ 7│ 8│
├─┼──┼──┤
│9│10│11│
└─┴──┴──┘
</pre><pre class="verbatim">(ra-format (ra-reshape a 0 2 2))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%3d:2:2:3─┬──║
║0│1│2║6│ 7│ 8║
║─┼─┼─║─┼──┼──║
║3│4│5║9│10│11║
║─┴─┴─║─┴──┴──║
</pre></div>

<p>The result of <code>ra-reshape</code> always shares the root of <var>a</var>.
</p>
<p>It is an error if the product of the lengths in <var>bounds</var> exceeds the length of axis <var>k</var> of <var>a</var>. For example
</p>
<div class="example">
<pre class="verbatim">(ra-reshape (ra-i 8 2) 0 2 3)
</pre><pre class="example">&rArr; <code>#%3d:2:3:2(((0 1) (2 3) (4 5)) ((6 7) (8 9) (10 11))</code> ; ok, 8 can be reshaped into 2·3
</pre><pre class="verbatim">(ra-reshape (ra-i 8 2) 0 4 3)
</pre><pre class="example">&rArr; error ; 8 cannot be reshaped into 4·3
</pre></div>

<span id="index-bounds-1"></span>
<p><code>ra-reshape</code> may be used to change either of the bounds of an axis, not only its length. For example
</p>
<div class="example">
<pre class="verbatim">(ra-format (ra-i 2 3))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2d:2:3
│0│1│2│
├─┼─┼─┤
│3│4│5│
└─┴─┴─┘
</pre></div>

<div class="example">
<pre class="verbatim">(ra-format (ra-reshape (ra-i 2 3) 0 '(1 2)))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2d@1:2:3
│0│1│2│
├─┼─┼─┤
│3│4│5│
└─┴─┴─┘
</pre></div>

<p>See also: <a href="#x_002dra_002dravel"><code>ra-ravel</code></a>, <a href="#x_002dra_002dtile"><code>ra-tile</code></a>, <a href="#Reshaping">Reshaping</a>.
</p>
</dd></dl>

<span id="index-_005b_003f_005d_002c-reverse"></span>
<span id="index-ra_002dreverse"></span>
<span id="x_002dra_002dreverse"></span><dl class="def">
<dt id="index-ra_002dreverse-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-reverse</strong> <em>a axes ... &rArr; b</em><a href='#index-ra_002dreverse-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Reverse the given <var>axes</var> of <var>a</var>.
</p>
<div class="example">
<pre class="verbatim">(ra-reverse (ra-i 2 3) 0 1)
</pre><pre class="example">&rArr; #%1d:2:3((5 4 3) (2 1 0))
</pre></div>

<p>The reversed array shares the root of <var>a</var>.
</p>
<p>See also: <a href="#x_002dra_002drotate"><code>ra-rotate</code></a>, <a href="#x_002dra_002drotate"><code>ra-rotate!</code></a>.
</p>
</dd></dl>

<span id="index-_005b_003f_005d_002c-rotate"></span>
<span id="index-_005b_003f_005d_002c-rowel"></span>
<span id="index-ra_002drotate"></span>
<span id="x_002dra_002drotate"></span><dl class="def">
<dt id="index-ra_002drotate-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-rotate</strong> <em>n a &rArr; b</em><a href='#index-ra_002drotate-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>(FIXME: not implemented) Rotate the first axis of <var>a</var> toward the lower indices (‘to the left’) <var>n</var> times. <var>n</var> may be any integer. The result has the type of <var>a</var>, unless that type is <code>d</code>, in which case the result is of type <code>#t</code>.
</p>
<p>This function always returns a new array.
</p>
<p>Example:
</p><div class="example">
<pre class="verbatim">(ra-rotate 1 (ra-i 3 2))
</pre><pre class="example">&rArr; #%1:3:2((2 3) (4 5) (0 1))
</pre></div>

<p>See also: <a href="#x_002dra_002drotate_0021"><code>ra-rotate!</code></a>, <a href="#x_002dra_002dreverse"><code>ra-reverse</code></a>.
</p>
</dd></dl>

<span id="index-rotate_0021"></span>
<span id="index-ra_002drotate_0021"></span>
<span id="x_002dra_002drotate_0021"></span><dl class="def">
<dt id="index-ra_002drotate_0021-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-rotate!</strong> <em>n a &rArr; a</em><a href='#index-ra_002drotate_0021-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Rotate in place the first axis of <var>a</var> to the left <var>n</var> times. <var>n</var> may be any integer. <var>a</var> must be writable. This function returns <var>a</var>.
</p>
<p>Example:
</p><div class="example">
<pre class="verbatim">(define a (ra-copy #t (ra-i 3 2)))
(ra-rotate! 1 a)
a
</pre><pre class="example">&rArr; #%1:3:2((2 3) (4 5) (0 1))
</pre></div>

<p>See also: <a href="#x_002dra_002drotate"><code>ra-rotate</code></a>, <a href="#x_002dra_002dreverse"><code>ra-reverse</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dscat"></span>
<span id="x_002dra_002dscat"></span><dl class="def">
<dt id="index-ra_002dscat-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-scat</strong> <em>type i a ... &rArr; b</em><a href='#index-ra_002dscat-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Concatenate <var>i</var>-items of arrays <var>a</var> ... . The arguments are suffix-matched and rank extended before concatenation. All axes must match, other than the concatenation axis.
</p>
<p>This function always produces a new array, of the type given. If <var>type</var> is <code>#f</code> then the type of the first <var>a</var> is used, unless that is <code>d</code>, in which case <code>#t</code> is used. The lower bound in the concatenation axis of the result is 0; the lower bounds of the arguments in the concatenation axis are ignored.
</p>
<div class="example">
<pre class="verbatim">(ra-scat #t 1 #%2((0 1) (2 3)) #%(a b))
</pre><pre class="example">&rArr; #%2((0 1) (2 3) (a b))
</pre></div>

<p>See also: <a href="#x_002dra_002dcat"><code>ra-cat</code></a>, <a href="#x_002dra_002dtile"><code>ra-tile</code></a>, <a href="#Concatenation">Concatenation</a>.
</p>
</dd></dl>

<span id="index-ra_002dshape"></span>
<span id="x_002dra_002dshape"></span><dl class="def">
<dt id="index-ra_002dshape-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-shape</strong> <em>a &rArr; s</em><a href='#index-ra_002dshape-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Return the shape (a list of two-element lists, each containing the lower and upper bound of each axis) of array <var>a</var>.
</p>
<div class="example">
<pre class="verbatim">(ra-shape (make-ra 0 '(2 3) 4))
</pre><pre class="example">&rArr; <code>((2 3) (0 3))</code>
</pre></div>

<p>See also: <a href="#x_002dra_002ddimensions"><code>ra-dimensions</code></a>, <a href="#x_002dmake_002dra"><code>make-ra</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dtile"></span>
<span id="x_002dra_002dtile"></span><dl class="def">
<dt id="index-ra_002dtile-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-tile</strong> <em>a k bounds ... &rArr; b</em><a href='#index-ra_002dtile-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Replicate array <var>a</var> by inserting axes of <var>bounds</var> ... before axis <var>k</var>. If <var>t</var> is the shape of <var>a</var>, the shape of the result will be
</p>
<div class="example">
<pre class="verbatim">[t₀ ... tₖ₋₁ s₀ ... tₖ ...]
</pre></div>

<p>Each of the bounds may be an integer (a length) or a pair of integers (lower and upper bounds).
</p>
<div class="example">
<pre class="verbatim">(define a (ra-i 3 4))
(ra-format a)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2d:3:4──┐
│0│1│ 2│ 3│
├─┼─┼──┼──┤
│4│5│ 6│ 7│
├─┼─┼──┼──┤
│8│9│10│11│
└─┴─┴──┴──┘
</pre></div>

<div class="example">
<pre class="verbatim">(ra-format (ra-tile a 0 2))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%3d:2:3:4║─┬─┬──┬──║
║0│1│ 2│ 3║0│1│ 2│ 3║
║─┼─┼──┼──║─┼─┼──┼──║
║4│5│ 6│ 7║4│5│ 6│ 7║
║─┼─┼──┼──║─┼─┼──┼──║
║8│9│10│11║8│9│10│11║
║─┴─┴──┴──║─┴─┴──┴──║
</pre></div>

<div class="example">
<pre class="verbatim">(ra-format (ra-tile a 1 2))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%3d:3:2:4┬─┬─┬─║─┬─┬──┬──║
║0│1│2│3║4│5│6│7║8│9│10│11║
║─┼─┼─┼─║─┼─┼─┼─║─┼─┼──┼──║
║0│1│2│3║4│5│6│7║8│9│10│11║
║─┴─┴─┴─║─┴─┴─┴─║─┴─┴──┴──║
</pre></div>

<div class="example">
<pre class="verbatim">(ra-format (ra-tile a 2 2))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%3d:3:4:2─┬──║
║0│0║4│4║ 8│ 8║
║─┼─║─┼─║──┼──║
║1│1║5│5║ 9│ 9║
║─┼─║─┼─║──┼──║
║2│2║6│6║10│10║
║─┼─║─┼─║──┼──║
║3│3║7│7║11│11║
║─┴─║─┴─║──┴──║
</pre></div>

<p>Either <var>len</var> or <var>hi</var> being <code>#f</code> creates <a href="#x_002ddead_002daxes">dead axes</a>.
</p><div class="example">
<pre class="verbatim">(define a (ra-tile (ra-i 2 2) 0 #f #f))
(define b (ra-transpose (ra-i 2 2) 2)) ; same thing
</pre><pre class="example">&rArr; <code>#%4d:d:d:2:2((((0 1) (2 3))))</code>
</pre></div>

<p>The tiled array shares the root of <var>a</var>.
</p>
<p>See also: <a href="#x_002dra_002dravel"><code>ra-ravel</code></a>, <a href="#x_002dra_002dreshape"><code>ra-reshape</code></a>, <a href="#Reshaping">Reshaping</a>.
</p>
</dd></dl>

<span id="index-ra_002dtranspose"></span>
<span id="x_002dra_002dtranspose"></span><dl class="def">
<dt id="index-ra_002dtranspose-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-transpose</strong> <em>a axes ... &rArr; b</em><a href='#index-ra_002dtranspose-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Transpose each axis 0, 1, ... of <var>a</var> to matching destination <var>axes</var>.
</p>
<div class="example">
<pre class="verbatim">(ra-transpose (ra-i 2 3) 1 0)
</pre><pre class="example">&rArr; #%1d:3:2((0 3) (1 4) (2 5))
</pre></div>

<p>The transposed array shares the root of <var>a</var>.
</p>
<p>See also: <a href="#x_002dra_002duntranspose"><code>ra-untranspose</code></a>, <a href="#Transposition">Transposition</a>.
</p>
</dd></dl>

<span id="index-ra_002duntranspose"></span>
<span id="x_002dra_002duntranspose"></span><dl class="def">
<dt id="index-ra_002duntranspose-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-untranspose</strong> <em>a axes ... &rArr; b</em><a href='#index-ra_002duntranspose-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Transpose <var>axes</var> of <var>a</var> to matching destination axes 0, 1, ...
</p>
<div class="example">
<pre class="verbatim">(ra-untranspose (ra-transpose (ra-i 2 3 4) 2 1 0) 2 1 0)
</pre><pre class="example">&rArr; <code>#%3d:2:3:4(((0 1 2 3) (4 5 6 7) (8 9 10 11)) ((12 13 14 15) (16 17 18 19) (20 21 22 23)))</code>
</pre></div>

<p>but
</p>
<div class="example">
<pre class="verbatim">(ra-transpose (ra-transpose (ra-i 2 3 4) 2 1 0) 2 1 0)
</pre><pre class="example">&rArr; <code>#%3d:4:2:3(((0 4 8) (12 16 20)) ((1 5 9) (13 17 21)) ((2 6 10) (14 18 22)) ((3 7 11) (15 19 23)))</code>
</pre></div>

<p>The transposed array shares the root of <var>a</var>.
</p>
<p>See also: <a href="#x_002dra_002dtranspose"><code>ra-transpose</code></a>, <a href="#Transposition">Transposition</a>.
</p>
</dd></dl>

<span id="index-ra_002dindex_002dmap_0021"></span>
<span id="x_002dra_002dindex_002dmap_0021"></span><dl class="def">
<dt id="index-ra_002dindex_002dmap_0021-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-index-map!</strong> <em>a op &rArr; a</em><a href='#index-ra_002dindex_002dmap_0021-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Iterate over array <var>a</var> in unspecified order, assigning to each element the result of <code>(op i₀ ...)</code>, where <code>i₀ ...</code> are the indices of that element.
</p>
<p>For example:
</p>
<div class="example">
<pre class="verbatim">(ra-index-map! (make-ra #t 3 4) -)
(ra-map! (make-ra #t 3 4) - (ra-iota) (ra-transpose (ra-iota) 1)) ; same thing
</pre><pre class="example">&rArr; <code>#%2:3:4((0 -1 -2 -3) (1 0 -1 -2) (2 1 0 -1))</code>
</pre></div>

<p>See also: <a href="#x_002dra_002dmap_0021"><code>ra-map!</code></a>, <a href="#Iteration">Iteration</a>.
</p>
</dd></dl>

<span id="index-ra_002dslice_002dfor_002deach"></span>
<span id="x_002dra_002dslice_002dfor_002deach"></span><dl class="def">
<dt id="index-ra_002dslice_002dfor_002deach-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-slice-for-each</strong> <em>k op a ...</em><a href='#index-ra_002dslice_002dfor_002deach-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Iterate over the <var>k</var>-frames of arrays <var>a</var> ..., applying <var>op</var> to the respective slices. The arguments <var>a</var> ... must have matching shapes over their <var>k</var>-frames.
</p>
<p>Note that it isn&rsquo;t necessary for arguments <var>a</var> to have rank ≥ <var>k</var>. Arguments with rank &lt; <var>k</var> are rank-extended and the corresponding arguments are 0-cells. For example:
</p>
<div class="example">
<pre class="verbatim">(ra-slice-for-each 1
  (lambda (a b) (display (list (a) (b))))
  (make-ra-root #(a b))
  (ra-i 2 3))
</pre><pre class="example">&rArr; <code>(a #%1d:3(0 1 2))(b #%1d:3(3 4 5))</code>
</pre></div>

<div class="example">
<pre class="verbatim">(ra-slice-for-each 2
  (lambda (a b) (display (list (a) (b))))
  (make-ra-root #(a b))
  (ra-i 2 3))
</pre><pre class="example">&rArr; <code>(a 0)(a 1)(a 2)(b 3)(b 4)(b 5)</code>
</pre></div>

<p>See also: <a href="#x_002dra_002dmap_0021"><code>ra-map!</code></a>, <a href="#x_002dra_002dfor_002deach"><code>ra-for-each</code></a>, <a href="#Iteration">Iteration</a>.
</p>
</dd></dl>

<span id="index-ra_002dmap_0021"></span>
<span id="x_002dra_002dmap_0021"></span><dl class="def">
<dt id="index-ra_002dmap_0021-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-map!</strong> <em>dst op a ... &rArr; dst</em><a href='#index-ra_002dmap_0021-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Iterate over arrays <var>dst</var> <var>a</var> ... applying <var>op</var> to the respective elements in <var>a</var>, and storing the result in the respective element of <var>dst</var>. The arguments must have matching shapes and the type of <var>dst</var> must be compatible with the results of <var>op</var>.
</p>
<p>This is equivalent to
</p><pre class="verbatim">(apply ra-slice-for-each
       (rank dst)
       (lambda (dst . a)
         (ra-set! dst (apply op (map ra-ref a))))
       dst a)
</pre>
<p>See also: <a href="#x_002dra_002dmap"><code>ra-map</code></a>, <a href="#x_002dra_002dfor_002deach"><code>ra-for-each</code></a>, <a href="#x_002dra_002dslice_002dfor_002deach"><code>ra-slice-for-each</code></a>, <a href="#Iteration">Iteration</a>.
</p>
</dd></dl>

<span id="index-ra_002dmap"></span>
<span id="x_002dra_002dmap"></span><dl class="def">
<dt id="index-ra_002dmap-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-map</strong> <em>type op a0 a ... &rArr; dst</em><a href='#index-ra_002dmap-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Same as <a href="#x_002dra_002dmap_0021"><code>ra-map!</code></a>, but create the result array from the arguments. Unlike <code>ra-map!</code>, this function requires at least one source argument.
</p>
<p>The type of <var>dst</var> is <var>type</var> unless that is <code>#f</code>, in which case the type of <var>a0</var> is used,  unless that is <code>'d</code>, in which case the <code>#f</code> is used. For the computation of the shape of <var>dst</var> see <a href="#Automatic-result-arrays">Automatic result arrays</a>.
</p>
<div class="example">
<pre class="verbatim">(ra-format (ra-map 'f64 + (ra-iota 3 1) (ra-i 3 4)))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2f64:3:4┬────┬────┐
│ 1.0│ 2.0│ 3.0│ 4.0│
├────┼────┼────┼────┤
│ 6.0│ 7.0│ 8.0│ 9.0│
├────┼────┼────┼────┤
│11.0│12.0│13.0│14.0│
└────┴────┴────┴────┘
</pre></div>

<p>See also: <a href="#x_002dra_002dmap_0021"><code>ra-map!</code></a>, <a href="#x_002dra_002dcopy"><code>ra-copy</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dcopy_0021"></span>
<span id="x_002dra_002dcopy_0021"></span><dl class="def">
<dt id="index-ra_002dcopy_0021-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-copy!</strong> <em>dst src &rArr; dst</em><a href='#index-ra_002dcopy_0021-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Copy <var>src</var> to <var>dst</var>. The arguments must have matching shapes and be of compatible types.
</p>
<p>For valid arguments, this is equivalent to any one of
</p><pre class="verbatim">(ra-map! dst identity src)
(ra-amend! dst src)
</pre>
<p>See also <a href="#x_002dra_002dcopy"><code>ra-copy</code></a> <a href="#x_002dra_002damend_0021"><code>ra-amend!</code></a> <a href="#x_002dra_002dset_0021"><code>ra-set!</code></a> <a href="#x_002dra_002dmap_0021"><code>ra-map!</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dcopy"></span>
<span id="x_002dra_002dcopy"></span><dl class="def">
<dt id="index-ra_002dcopy-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-copy</strong> <em>src &rArr; dst</em><a href='#index-ra_002dcopy-1' class='copiable-anchor'> &para;</a></span></dt>
<dt id="index-ra_002dcopy-2"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-copy</strong> <em>type src &rArr; dst</em><a href='#index-ra_002dcopy-2' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Create a new array of type <var>type</var> and copy <var>src</var> into it. If <var>type</var> is <code>#f</code> or isn&rsquo;t given, use the type of <var>src</var>, unless that type is <code>d</code>, in which case the result is of type <code>#t</code>.
</p>
<p>See also <a href="#x_002dra_002dcopy_0021"><code>ra-copy!</code></a> <a href="#x_002dra_002damend_0021"><code>ra-amend!</code></a> <a href="#x_002dra_002dset_0021"><code>ra-set!</code></a>.
</p></dd></dl>

<span id="index-ra_002dswap_0021"></span>
<span id="x_002dra_002dswap_0021"></span><dl class="def">
<dt id="index-ra_002dswap_0021-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-swap!</strong> <em>a b &rArr; a</em><a href='#index-ra_002dswap_0021-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Swap the contents of <var>a</var> and <var>b</var>. The swap is executed in unspecified order, so the effect on <var>a</var> and <var>b</var> is undefined if <var>a</var> and <var>b</var> share storage.
</p>
<div class="example">
<pre class="verbatim">(ra-swap! (make-ra 2 3) (make-typed-ra 'f64 -1 3))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%1:3(-1.0 -1.0 -1.0)
</pre></div>

<p>See also <a href="#x_002dra_002dswap_002din_002dorder_0021"><code>ra-swap-in-order!</code></a> <a href="#x_002dra_002dcopy_0021"><code>ra-copy!</code></a>.
</p></dd></dl>

<span id="index-ra_002dswap_002din_002dorder_0021"></span>
<span id="x_002dra_002dswap_002din_002dorder_0021"></span><dl class="def">
<dt id="index-ra_002dswap_002din_002dorder_0021-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-swap-in-order!</strong> <em>a b &rArr; a</em><a href='#index-ra_002dswap_002din_002dorder_0021-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Swap the contents of <var>a</var> and <var>b</var>. The swap is executed in row-major order.
</p></dd></dl>

<span id="index-ra_002dfill_0021"></span>
<span id="x_002dra_002dfill_0021"></span><dl class="def">
<dt id="index-ra_002dfill_0021-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-fill!</strong> <em>dst value &rArr; dst</em><a href='#index-ra_002dfill_0021-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Assign <var>value</var> to each element of <var>dst</var>. The arguments must be of compatible types.
</p>
<p>This is equivalent to any one of
</p><div class="example">
<pre class="verbatim">(ra-map! dst (const value))
(ra-copy! dst (make-ra value))
(ra-amend! dst (make-ra value))
(ra-amend! dst value) ; as long as value isn't an array
</pre></div>

<p>Compare
</p>
<div class="example">
<pre class="verbatim">(ra-fill! (make-ra #f 2 2) (make-ra 'x))
</pre><pre class="example">&rArr; #%2:2:2((#%0(x) #%0(x)) (#%0(x) #%0(x)))
</pre><pre class="verbatim">(ra-amend! (make-ra #f 2 2) 'x)
</pre><pre class="example">&rArr; #%2:2:2((x x) (x x))
</pre><pre class="verbatim">(ra-amend! (make-ra #f 2 2) (make-ra 'x))
</pre><pre class="example">&rArr; #%2:2:2((x x) (x x))
</pre><pre class="verbatim">(ra-amend! (make-ra #f 2 2) (make-ra (make-ra 'x)))
</pre><pre class="example">&rArr; #%2:2:2((#%0(x) #%0(x)) (#%0(x) #%0(x)))
</pre></div>

<p>See also: <a href="#x_002dra_002dset_0021"><code>ra-set!</code></a>, <a href="#x_002dra_002dcopy_0021"><code>ra-copy!</code></a>, <a href="#x_002dra_002damend_0021"><code>ra-amend!</code></a>.
</p>
</dd></dl>

<span id="index-packed-array-2"></span>
<span id="index-ra_002dorder_002dc_003f"></span>
<span id="x_002dra_002dorder_002dc_003f"></span><dl class="def">
<dt id="index-ra_002dorder_002dc_003f-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-order-c?</strong> <em>a [n [org]]</em><a href='#index-ra_002dorder_002dc_003f-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Check whether axes [<var>org</var> ... <var>org</var>+<var>n</var>) of <var>a</var> are in row-major order. By default, check that the whole array is in row-major order, and additionally that the step on the last axis is 1 (i.e. the array is ‘packed’).
</p>
<p><code>(ra-order-c? a n org)</code> implies <code>(eq? (ra-root a) (ra-root (<a href="#x_002dra_002dravel"><code>ra-ravel</code></a> a n org)))</code>. Note that the stronger condition <code>(ra-order-c? a)</code> is not necessary for <code>(eq? (ra-root a) (ra-root (ra-ravel a)))</code> to hold.
</p>
</dd></dl>

<span id="index-ra_002dref"></span>
<span id="x_002dra_002dref"></span><dl class="def">
<dt id="index-ra_002dref-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-ref</strong> <em>a i ...</em><a href='#index-ra_002dref-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Look up array element. It is an error if the number of <var>i ...</var> doesn&rsquo;t match the rank of <var>a</var>.
</p>
<p>See also: <a href="#x_002dra_002dcell"><code>ra-cell</code></a>, <a href="#x_002dra_002dslice"><code>ra-slice</code></a>, <a href="#x_002dra_002dfrom"><code>ra-from</code></a>, <a href="#x_002dra_002dset_0021"><code>ra-set!</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dset_0021"></span>
<span id="x_002dra_002dset_0021"></span><dl class="def">
<dt id="index-ra_002dset_0021-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-set!</strong> <em>a o i ...</em><a href='#index-ra_002dset_0021-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Assign array element. It is an error if the number of <var>i ...</var> doesn&rsquo;t match the rank of <var>a</var>.
</p>
<p>See also: <a href="#x_002dra_002damend_0021"><code>ra-amend!</code></a>, <a href="#x_002dra_002dref"><code>ra-ref</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dslice"></span>
<span id="x_002dra_002dslice"></span><dl class="def">
<dt id="index-ra_002dslice-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-slice</strong> <em>a i ...</em><a href='#index-ra_002dslice-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Look up array cell.
</p>
<p>This function returns a view of <var>a</var> with rank <var>k</var> equal to the rank of <var>a</var> minus the number of <var>i ...</var>, even if that is 0.
</p>
<p>It is an error if the number of <var>i ...</var> exceeds the rank of <var>a</var>.
</p>
<p>See also: <a href="#x_002dra_002dcell"><code>ra-cell</code></a>, <a href="#x_002dra_002dref"><code>ra-ref</code></a>, <a href="#x_002dra_002dfrom"><code>ra-from</code></a>, <a href="#Slicing">Slicing</a>.
</p></dd></dl>

<span id="index-ra_002dcell"></span>
<span id="x_002dra_002dcell"></span><dl class="def">
<dt id="index-ra_002dcell-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-cell</strong> <em>a i ...</em><a href='#index-ra_002dcell-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Look up array cell.
</p>
<p>Let <var>k</var> be the rank of <var>a</var> minus the number of <var>i ...</var>. If <var>k</var> is zero, return the array element at <var>i ...</var>, like <a href="#x_002dra_002dref"><code>ra-ref</code></a>; else return a <var>k</var>-view of <var>a</var>, like <a href="#x_002dra_002dslice"><code>ra-slice</code></a>.
</p>
<p>It is an error if the number of <var>i ...</var> exceeds the rank of <var>a</var>.
</p>
<div class="example">
<pre class="verbatim">(define a (ra-copy (ra-i 3 2)))
(ra-cell a 0)
(ra-slice a 0) ; same thing
</pre><pre class="example">&rArr; <code>#%1(0 1 2)</code>
</pre><pre class="verbatim">(ra-slice a 0 1)
</pre><pre class="example">&rArr; <code>#%0(4)</code>
</pre><pre class="verbatim">(ra-cell a 0 1)
(ra-ref a 0 1) ; same thing
</pre><pre class="example">&rArr; <code>4</code>
</pre></div>

<p>See also: <a href="#x_002dra_002dslice"><code>ra-slice</code></a>, <a href="#x_002dra_002dref"><code>ra-ref</code></a>, <a href="#x_002dra_002dfrom"><code>ra-from</code></a>, <a href="#Slicing">Slicing</a>.
</p>
</dd></dl>

<span id="index-ra_002dequal_003f"></span>
<span id="x_002dra_002dequal_003f"></span><dl class="def">
<dt id="index-ra_002dequal_003f-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-equal?</strong> <em>a ... → boolean</em><a href='#index-ra_002dequal_003f-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Return <code>#t</code> if the arrays <var>a</var> ... have the same shapes and types and their
corresponding elements are all <code>equal?</code> to each other, or <code>#f</code> otherwise.
</p>
<p>Note that this function isn&rsquo;t rank extending; the shapes of the arguments must be the same, not just match. Here&rsquo;s a rank-extending version:
</p>
<div class="example">
<pre class="verbatim">(import (ice-9 control))
(define (ra-equal?* . a) (let/ec exit (apply ra-for-each (lambda a (unless (apply equal? a) (exit #f))) a) #t))
</pre></div>

<p>See also: <a href="#x_002dra_002dfor_002deach"><code>ra-for-each</code></a>, <a href="#x_002dra_002dfold"><code>ra-fold</code></a>, <a href="#x_002dra_002devery"><code>ra-every</code></a>, <a href="#x_002dra_002dany"><code>ra-any</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dfor_002deach"></span>
<span id="x_002dra_002dfor_002deach"></span><dl class="def">
<dt id="index-ra_002dfor_002deach-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-for-each</strong> <em>op a ...</em><a href='#index-ra_002dfor_002deach-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>See also: <a href="#x_002dra_002dslice_002dfor_002deach"><code>ra-slice-for-each</code></a>, <a href="#x_002dra_002dmap_0021"><code>ra-map</code></a>, <a href="#Iteration">Iteration</a>.
</p>
</dd></dl>

<span id="index-ra_002dfold"></span>
<span id="x_002dra_002dfold"></span><dl class="def">
<dt id="index-ra_002dfold-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-fold</strong> <em>op knil a ...</em><a href='#index-ra_002dfold-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>See also: <a href="#x_002dra_002devery"><code>ra-every</code></a>, <a href="#x_002dra_002dany"><code>ra-any</code></a>, <a href="#Iteration">Iteration</a>.
</p>
</dd></dl>

<span id="index-ra_002devery"></span>
<span id="x_002dra_002devery"></span><dl class="def">
<dt id="index-ra_002devery-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-every</strong> <em>pred? a ...</em><a href='#index-ra_002devery-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>See also: <a href="#x_002dra_002dfold"><code>ra-fold</code></a>, <a href="#x_002dra_002dany"><code>ra-any</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dany"></span>
<span id="x_002dra_002dany"></span><dl class="def">
<dt id="index-ra_002dany-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-any</strong> <em>pred? a ...</em><a href='#index-ra_002dany-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>See also: <a href="#x_002dra_002dfold"><code>ra-fold</code></a>, <a href="#x_002dra_002devery"><code>ra-every</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dfrom"></span>
<span id="x_002dra_002dfrom"></span><dl class="def">
<dt id="index-ra_002dfrom-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-from</strong> <em>a i ... → b</em><a href='#index-ra_002dfrom-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Outer product slice of <var>a</var> by indices <var>i</var> ...
</p>
<p>The shape of <var>b</var> is the concatenation of the shapes of <var>i</var>... and the
contents are obtained by looking up in each dimension of <var>a</var> by the indices <var>i</var>,
that is
</p>
<div class="example">
<pre class="verbatim">b(j₀₀ j₀₁ ... j₁₀ j₁₁ ...) = a(i₀(j₀₀ j₀₁ ...) i₁(j₁₀ j₁₁ ...) ...)
</pre></div>

<p>where <var>i</var> : <var>i₀</var> <var>i₁</var> ... The special value <code>#t</code> is understood as the full range of <var>a</var> on that axis.
</p>
<p>Additionally, if each of the <var>i</var> ... is one of
</p><ul>
<li> <code>#t</code>
</li><li> an array of type <code>d</code>
</li><li> an array of rank 0
</li><li> an integer
</li></ul>
<p>then the result <var>b</var> shares the root of <var>a</var>. In all other cases a new root is allocated for the result. For example
</p>
<div class="example">
<pre class="verbatim">(define a (list-&gt;ra 2 '((1 2 3) (a b c))))
(define b (ra-from a #t (ra-iota 3 2 -1))) ; same as (ra-reverse a 1)
b
</pre><pre class="example">&rArr; <code>#%2:2:3((3 2 1) (c b a))</code>
</pre><pre class="verbatim">(eq? (ra-root a) (ra-root b))
</pre><pre class="example">&rArr; <code>#t</code>
</pre><pre class="verbatim">(define c (ra-from a #t (list-&gt;ra 1 '(2 1 0))))
b
</pre><pre class="example">&rArr; <code>#%2:2:3((3 2 1) (c b a))</code>
</pre><pre class="verbatim">(eq? (ra-root a) (ra-root c))
</pre><pre class="example">&rArr; <code>#f</code>
</pre></div>

<p>Unbounded indices aren&rsquo;t treated especially, so they are only valid if the relevant axis of <var>ra</var> is itself unbounded.
</p>
<div class="example">
<pre class="verbatim">(ra-i #t 4)
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2d:f:4──┐
│0│1│ 2│ 3│
├─┼─┼──┼──┤
│4│5│ 6│ 7│
├─┼─┼──┼──┤
│8│9│10│11│
...........
</pre><pre class="verbatim">(ra-from (ra-i #t 4) (ra-iota #f 0 2))
</pre><pre class="example">&rArr;
</pre><pre class="verbatim">#%2d:f:4─┬──┐
│ 0│ 1│ 2│ 3│
├──┼──┼──┼──┤
│ 8│ 9│10│11│
├──┼──┼──┼──┤
│16│17│18│19│
.............
</pre></div>

<p><i>If the result would have rank 0, then an array element is returned, and not a 0-rank view of <var>a</var>. Use <a href="#x_002dra_002damend_0021"><code>ra-amend!</code></a> to assign to cells of an array regardless of whether they are of 0-rank or higher.</i>
</p>
<p>The type of <var>b</var> is the same as that of <var>a</var>, with the only exception that if the type of <var>a</var> is <code>d</code> and the root of <var>b</var> cannot be shared with the root of <var>a</var>, then the type of <var>b</var> is <code>#t</code>.
</p>
<p>See also: <a href="#x_002dra_002dcell"><code>ra-cell</code></a>, <a href="#x_002dra_002dref"><code>ra-ref</code></a>, <a href="#x_002dra_002dslice"><code>ra-slice</code></a>, <a href="#x_002dra_002damend_0021"><code>ra-amend!</code></a>, <a href="#Slicing">Slicing</a>.<a id="DOCF11" href="#FOOT11"><sup>11</sup></a>
</p>
</dd></dl>

<span id="index-ra_002dfrom_002dcopy"></span>
<span id="x_002dra_002dfrom_002dcopy"></span><dl class="def">
<dt id="index-ra_002dfrom_002dcopy-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-from-copy</strong> <em>a i ... &rArr; b</em><a href='#index-ra_002dfrom_002dcopy-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Like <code>ra-from</code>, but always return a newly allocated array. This is equivalent to <code>(ra-copy (ra-from a i ...))</code>, but it doesn&rsquo;t incur a second copy in case <code>ra-from</code> already allocates a new array.
</p>
<p>See also: <a href="#x_002dra_002dfrom"><code>ra-from</code></a>.
</p>
</dd></dl>

<span id="index-ra_002damend_0021"></span>
<span id="x_002dra_002damend_0021"></span><dl class="def">
<dt id="index-ra_002damend_0021-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-amend!</strong> <em>a c i ... → a</em><a href='#index-ra_002damend_0021-1' class='copiable-anchor'> &para;</a></span></dt>
<dd><p>Copy <var>c</var> to the outer product slice of <var>a</var> by indices <var>i</var> ...
</p>
<div class="example">
<pre class="verbatim">a(i₀(j₀₀ j₀₁ ...) i₁(j₁₀ j₁₁ ...) ...) ← c(j₀₀ j₀₁ ... j₁₀ j₁₁ ...)
</pre></div>

<p>where <var>i</var> : <var>i₀</var> <var>i₁</var> ...
</p>
<p>This is equivalent to <code>(ra-copy! (ra-from a i ...) c)</code> if <code>(ra-from a i ...)</code> would
return a shared ra of <var>a</var>, but it also works in other cases, as long as <var>a</var> is
writable. <var>i</var> may take any of the special values accepted by <code>ra-from</code>.
</p>
<div class="example">
<pre class="verbatim">(define a (list-&gt;ra 1 '(1 2 3)))
(define x 1)
(define y (array-&gt;ra #(1)))
(ra-amend! a 9 x) ; modifies a
(ra-amend! a (array-&gt;ra #0(9)) x) ; same thing
(ra-copy! (ra-from a x) (array-&gt;ra #0(9))) ; modifies a
(ra-amend! a 9 y) ; modifies a
(ra-copy! (ra-from a y) (array-&gt;ra #0(9))) ; (ra-from a y) is a new array, so a is NOT modified
(ra-amend! (array-&gt;ra #(2 3 4)) 9 1) ; error, (array-&gt;ra #(2 3 4)) is not mutable
</pre></div>

<p>If <var>i</var> contains repeated indices or the steps of <var>a</var> make it so that the same elements of <var>a</var>
are referenced more than once, then the value that ends up in <var>a</var> may correspond to any of the
indices that match those elements. <code>newra</code> will <em>not</em> check that each element of <var>a</var> is represented uniquely in its root vector.
</p>
<div class="example">
<pre class="verbatim">(ra-amend! a (array-&gt;ra #(6 7 8)) (ra-tile (array-&gt;ra #0(1)) 0 3))
</pre><pre class="example">&rArr; #%1:3(1 8 3) ; do not rely on 8 ending up there
</pre></div>

<p>This function returns the modified array <var>a</var>.
</p>
<p>See also: <a href="#x_002dra_002dfrom"><code>ra-from</code></a>, <a href="#x_002dra_002dcopy_0021"><code>ra-copy!</code></a> <a href="#x_002dra_002dcell"><code>ra-cell</code></a> <a href="#x_002dra_002dref"><code>ra-ref</code></a> <a href="#x_002dra_002dslice"><code>ra-slice</code></a> <a href="#x_002dra_002dset_0021"><code>ra-set!</code></a>.
</p>
</dd></dl>


<span id="index-ra_002d_003earray"></span>
<span id="x_002dra_002d_003earray"></span><dl class="def">
<dt id="index-ra_002d_003earray-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-&gt;array</strong> <em>a</em><a href='#index-ra_002d_003earray-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Convert (<code>newra</code>) array <var>a</var> into built-in Guile array.
</p>
<p>This function does not create a copy of the array, but reuses the root (<code>ra-root</code>) of <var>a</var>, that is, <code>(eq? (ra-root a) (shared-array-root (ra-&gt;array a)))</code> is <code>#t</code>.
</p>
<p>Not all arrays can be converted into built-in Guile arrays. For example, type <code>d</code> arrays, or arrays with unbounded axes, are not convertible.
</p>
<div class="example">
<pre class="verbatim">(ra-&gt;array (ra-i 3)) ; error, type d not convertible
(ra-&gt;array (ra-copy (ra-i 3))) ; ok, (ra-copy (ra-i 3)) has type #t
(ra-&gt;array (ra-transpose (ra-i 2 3) 1)) ; error, not convertible
(ra-&gt;array (ra-singletonize (ra-transpose (ra-i 2 3) 1))) ; ok
</pre></div>

<p>See also: <a href="#x_002darray_002d_003era"><code>array-&gt;ra</code></a>, <a href="#x_002dra_002dsingletonize"><code>ra-singletonize</code></a>, <a href="#x_002dra_002dcopy_0021"><code>ra-copy!</code></a>.
</p>
</dd></dl>

<span id="index-ra_002dsingletonize"></span>
<span id="x_002dra_002dsingletonize"></span><dl class="def">
<dt id="index-ra_002dsingletonize-1"><span class="category">Function<!-- /@w -->: </span><span><strong>ra-singletonize</strong> <em>a</em><a href='#index-ra_002dsingletonize-1' class='copiable-anchor'> &para;</a></span></dt>
<dd>
<p>Return an array with the same root and dimensions as <var>a</var>, except that dead axes (axes with step 0 and undefined length) have their length set to 1.
</p>
<div class="example">
<pre class="verbatim">(ra-dimensions (ra-transpose (ra-i 2 3) 1))
</pre><pre class="example">&rArr; (#f 2 3)
</pre><pre class="verbatim">(ra-dimensions (ra-singletonize (ra-transpose (ra-i 2 3) 1)))
</pre><pre class="example">&rArr; (1 2 3)
</pre><pre class="verbatim">(ra-dimensions (ra-singletonize (ra-tile (ra-i 2 3) 0 4)))
</pre><pre class="example">&rArr; (4 2 3) ; no change
</pre></div>

</dd></dl>

<hr>
</div>
<div class="chapter" id="Cheatsheet">
<div class="header">
<p>
Next: <a href="#Sources" accesskey="n" rel="next">Sources</a>, Previous: <a href="#Reference" accesskey="p" rel="prev">Reference</a>, Up: <a href="#Top" accesskey="u" rel="up"><code>newra</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Cheatsheet-1"></span><h2 class="chapter">6 Cheatsheet</h2>

<hr>
</div>
<div class="chapter" id="Sources">
<div class="header">
<p>
Next: <a href="#Indices" accesskey="n" rel="next">Indices</a>, Previous: <a href="#Cheatsheet" accesskey="p" rel="prev">Cheatsheet</a>, Up: <a href="#Top" accesskey="u" rel="up"><code>newra</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Sources-1"></span><h2 class="chapter">7 Sources</h2>

<table>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="Abr70"></span>[Abr70]</td><td width="90%">Philip S. Abrams. An APL machine. Technical report SLAC-114 UC-32 (MISC), Stanford Linear Accelerator Center, Stanford University, Stanford, CA, USA, February 1970.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="Ber87"></span>[Ber87]</td><td width="90%">Robert Bernecky. An introduction to function rank. ACM SIGAPL APL Quote Quad, 18(2):39–43, December 1987.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="bli17"></span>[bli17]</td><td width="90%">The Blitz++ meta-template library. <a href="http://blitz.sourceforge.net">http://blitz.sourceforge.net</a>, November 2017.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="Cha86"></span>[Cha86]</td><td width="90%">Gregory J. Chaitin. Physics in APL2, June 1986.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="FI68"></span>[FI68]</td><td width="90%">Adin D. Falkoff and Kenneth Eugene Iverson. APL\360 User’s manual. IBM Thomas J. Watson Research Center, August 1968.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="FI73"></span>[FI73]</td><td width="90%">Adin D. Falkoff and Kenneth Eugene Iverson. The design of APL. IBM Journal of Research and Development, 17(4):5–14, July 1973.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="FI78"></span>[FI78]</td><td width="90%">Adin D. Falkoff and Kenneth Eugene Iverson. The evolution of APL. ACM SIGAPL APL, 9(1):30– 44, 1978.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="J-S"></span>[J S]</td><td width="90%">J Primer. J Software, <a href="https://www.jsoftware.com/help/primer/contents.htm">https://www.jsoftware.com/help/primer/contents.htm</a>, November 2017.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="Mat"></span>[Mat]</td><td width="90%">MathWorks. MATLAB documentation, <a href="https://www.mathworks.com/help/matlab/">https://www.mathworks.com/help/matlab/</a>, November 2017.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="num17"></span>[num17]</td><td width="90%">NumPy. <a href="http://www.numpy.org">http://www.numpy.org</a>, November 2017.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="Ric08"></span>[Ric08]</td><td width="90%">Henry Rich. J for C programmers, February 2008.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="SSM14"></span>[SSM14]</td><td width="90%">Justin Slepak, Olin Shivers, and Panagiotis Manolios. An array-oriented language with static rank polymorphism. In Z. Shao, editor, ESOP 2014, LNCS 8410, pages 27–46, 2014.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="Vel01"></span>[Vel01]</td><td width="90%">Todd Veldhuizen. Blitz++ user’s guide, February 2001.</td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="Wad90"></span>[Wad90]</td><td width="90%">Philip Wadler. Deforestation: transforming programs to eliminate trees. Theoretical Computer Science, 73(2): 231&ndash;248, June 1990. <a href="https://doi.org/10.1016/0304-3975%2890%2990147-A">https://doi.org/10.1016/0304-3975%2890%2990147-A</a></td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="SRFI_002d4"></span>[SRFI-4]</td><td width="90%">Marc Feeley. SRFI-4: Homogeneous numeric vector datatypes, May 1999. <a href="https://srfi.schemers.org/srfi-4/srfi-4.html">https://srfi.schemers.org/srfi-4/srfi-4.html</a></td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="SRFI_002d25"></span>[SRFI-25]</td><td width="90%">Jussi Piitulainen. SRFI-25: Multi-dimensional array primitives, May 2002. <a href="https://srfi.schemers.org/srfi-25/srfi-25.html">https://srfi.schemers.org/srfi-25/srfi-25.html</a></td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="SRFI_002d122"></span>[SRFI-122]</td><td width="90%">Bradley J. Lucier. SRFI-122: Nonempty intervals and generalized arrays, December 2016. <a href="https://srfi.schemers.org/srfi-122/srfi-122.html">https://srfi.schemers.org/srfi-122/srfi-122.html</a></td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="SRFI_002d160"></span>[SRFI-160]</td><td width="90%">John Cowan and Shiro Kawai. SRFI-160: Homogeneous numeric vector libraries, November 2020. <a href="https://srfi.schemers.org/srfi-160/srfi-160.html">https://srfi.schemers.org/srfi-160/srfi-160.html</a></td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="SRFI_002d163"></span>[SRFI-163]</td><td width="90%">Per Bothner. SRFI-163: Enhanced array literals, January 2019. <a href="https://srfi.schemers.org/srfi-163/srfi-163.html">https://srfi.schemers.org/srfi-163/srfi-163.html</a></td></tr>
<tr><td width="10%"></td></tr>
<tr><td width="10%"><span id="SRFI_002d164"></span>[SRFI-164]</td><td width="90%">Per Bothner. SRFI-164: Enhanced multi-dimensional arrays, August  2019. <a href="https://srfi.schemers.org/srfi-164/srfi-164.html">https://srfi.schemers.org/srfi-164/srfi-164.html</a></td></tr>
</table>

<hr>
</div>
<div class="unnumbered" id="Indices">
<div class="header">
<p>
Previous: <a href="#Sources" accesskey="p" rel="prev">Sources</a>, Up: <a href="#Top" accesskey="u" rel="up"><code>newra</code></a> &nbsp; [<a href="#Indices" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Indices-1"></span><h2 class="unnumbered">Indices</h2>

<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Indices_cp_symbol-1"><b>*</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-2"><b>,</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-3"><b>{</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-4"><b>⊖</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-5"><b>⌽</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-6"><b>⍉</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-7"><b>⍋</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-8"><b>⍴</b></a>
 &nbsp; 
<br>
<a class="summary-letter" href="#Indices_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-U"><b>U</b></a>
 &nbsp; 
</td></tr></table>
<table class="index-cp" border="0">
<tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_symbol-1">*</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002ara_002dparenthesized_002drank_002dzero_002a"><code>*ra-parenthesized-rank-zero*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Writing-and-reading">Writing and reading</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002ara_002dprint_002a"><code>*ra-print*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Writing-and-reading">Writing and reading</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_symbol-2">,</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002c_002c-ravel"><code>,</code>, ravel</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reshaping">Reshaping</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_symbol-3">{</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_007b_002c-from"><code>{</code>, from</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Slicing">Slicing</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_symbol-4">⊖</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005b_003f_005d_002c-rowel"><code>⊖</code>, rowel</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_symbol-5">⌽</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005b_003f_005d_002c-reverse"><code>⌽</code>, reverse</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005b_003f_005d_002c-rotate"><code>⌽</code>, rotate</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_symbol-6">⍉</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005b_003f_005d_002c-transpose"><code>⍉</code>, transpose</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Transposition">Transposition</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_symbol-7">⍋</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005b_003f_005d">⍋</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Transposition">Transposition</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_symbol-8">⍴</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005b_003f_005d_002c-reshape"><code>⍴</code>, reshape</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reshaping">Reshaping</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-A">A</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-APL">APL</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reshaping">Reshaping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-APL-1">APL</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Differences-with_002e_002e_002e">Differences with...</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-array_002d_003era"><code>array-&gt;ra</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-B">B</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-bounds">bounds</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Introduction">Introduction</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-bounds-1">bounds</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-box"><code>box</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Writing-and-reading">Writing and reading</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-box_002dcompact"><code>box-compact</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Writing-and-reading">Writing and reading</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-broadcasting_002c-singleton_002c-newaxis">broadcasting, singleton, newaxis</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-C">C</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-c_002ddims"><code>c-dims</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cell">cell</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-concatenation">concatenation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Concatenation">Concatenation</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-D">D</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-d"><code>d</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Special-arrays">Special arrays</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-dead-axes">dead axes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Special-arrays">Special arrays</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-default"><code>default</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Writing-and-reading">Writing and reading</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-diagonal">diagonal</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Transposition">Transposition</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-dim-vector">dim vector</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-pieces-of-an-array">The pieces of an array</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-F">F</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Fortran">Fortran</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Differences-with_002e_002e_002e">Differences with...</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-frame">frame</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-G">G</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-grade">grade</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Transposition">Transposition</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-I">I</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-index-placeholder">index placeholder</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Transposition">Transposition</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-infinite-axes">infinite axes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Special-arrays">Special arrays</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-intersection">intersection</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-L">L</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-ldots"><code>ldots</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Slicing">Slicing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ldots-1"><code>ldots</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-libguile">libguile</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Built_002din-Guile-arrays">Built-in Guile arrays</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-M">M</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002daseq"><code>make-aseq</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Special-arrays">Special arrays</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dra"><code>make-ra</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dra_002dnew"><code>make-ra-new</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dra_002droot"><code>make-ra-root</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dtyped_002dra"><code>make-typed-ra</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Matlab">Matlab</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Differences-with_002e_002e_002e">Differences with...</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-N">N</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-new-array">new array</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-pieces-of-an-array">The pieces of an array</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Numpy">Numpy</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Numpy-1">Numpy</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-NumPy">NumPy</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Differences-with_002e_002e_002e">Differences with...</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-O">O</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Octave">Octave</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Differences-with_002e_002e_002e">Differences with...</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-order_002c-C">order, C</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-order_002c-row_002dmajor">order, row-major</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-outer-product">outer product</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Transposition">Transposition</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-P">P</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-packed-array">packed array</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-packed-array-1">packed array</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-packed-array-2">packed array</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-prefix-matching">prefix matching</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iteration">Iteration</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-prefix-matching-1">prefix matching</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Transposition">Transposition</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-prefix-slice">prefix slice</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Creating-and-accessing-arrays">Creating and accessing arrays</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-prefix-slice-1">prefix slice</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Slicing">Slicing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-print-prefix"><code>print prefix</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Python">Python</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Differences-with_002e_002e_002e">Differences with...</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-R">R</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002d_003earray"><code>ra-&gt;array</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002damend_0021"><code>ra-amend!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dany"><code>ra-any</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dcat"><code>ra-cat</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dcell"><code>ra-cell</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dclip"><code>ra-clip</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dcopy"><code>ra-copy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dcopy_0021"><code>ra-copy!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002ddimensions"><code>ra-dimensions</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dequal_003f"><code>ra-equal?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002devery"><code>ra-every</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dfill_0021"><code>ra-fill!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dfold"><code>ra-fold</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dfor_002deach"><code>ra-for-each</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dformat"><code>ra-format</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dfrom"><code>ra-from</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dfrom_002dcopy"><code>ra-from-copy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002di"><code>ra-i</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dindex_002dmap_0021"><code>ra-index-map!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002diota"><code>ra-iota</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dmap"><code>ra-map</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dmap_0021"><code>ra-map!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dorder_002dc_003f"><code>ra-order-c?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dprint"><code>ra-print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dprint_002dprefix"><code>ra-print-prefix</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dravel"><code>ra-ravel</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dref"><code>ra-ref</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dreshape"><code>ra-reshape</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dreverse"><code>ra-reverse</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002drotate"><code>ra-rotate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002drotate_0021"><code>ra-rotate!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dscat"><code>ra-scat</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dset_0021"><code>ra-set!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dshape"><code>ra-shape</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dsingletonize"><code>ra-singletonize</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dslice"><code>ra-slice</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dslice_002dfor_002deach"><code>ra-slice-for-each</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dswap_0021"><code>ra-swap!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dswap_002din_002dorder_0021"><code>ra-swap-in-order!</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dtile"><code>ra-tile</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002dtranspose"><code>ra-transpose</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ra_002duntranspose"><code>ra-untranspose</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-rank">rank</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-pieces-of-an-array">The pieces of an array</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-rank-polymorphism">rank polymorphism</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-polymorphism">Rank polymorphism</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-root-vector">root vector</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-pieces-of-an-array">The pieces of an array</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-rotate_0021">rotate!</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-S">S</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-shape-agreement_002c-prefix">shape agreement, prefix</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-shape-agreement_002c-suffix">shape agreement, suffix</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Rank-extension">Rank extension</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-shared-root">shared root</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-pieces-of-an-array">The pieces of an array</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-singleton-axis">singleton axis</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Special-arrays">Special arrays</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-SRFI_002d163">SRFI-163</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Writing-and-reading">Writing and reading</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-SRFI_002d163-1">SRFI-163</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reference">Reference</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-T">T</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-transpose">transpose</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Transposition">Transposition</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Indices_cp_letter-U">U</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-unbounded-axes">unbounded axes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Special-arrays">Special arrays</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Indices_cp_symbol-1"><b>*</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-2"><b>,</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-3"><b>{</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-4"><b>⊖</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-5"><b>⌽</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-6"><b>⍉</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-7"><b>⍋</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_symbol-8"><b>⍴</b></a>
 &nbsp; 
<br>
<a class="summary-letter" href="#Indices_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Indices_cp_letter-U"><b>U</b></a>
 &nbsp; 
</td></tr></table>


</div>
</div>
<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h5><a id="FOOT1" href="#DOCF1">(1)</a></h5>
<pre class="verbatim">(import (newra))
(define element (lambda i (format #f &quot;A(~{~a~^, ~})&quot; i)))
(define (ti k) (ra-transpose (ra-iota) k))
(ra-format (ra-map! (make-ra #f 3 3)  element (ti 0) (ti 1)) #:prefix? #f)
(ra-format (ra-map! (make-ra #f 2 '(2 5) '(-2 0))  element (ti 0) (ti 1) (ti 2)) #:prefix? #f)
</pre>
<h5><a id="FOOT2" href="#DOCF2">(2)</a></h5>
<p>Cf. <a href="https://en.wikipedia.org/wiki/Dope_vector"><em>dope vector</em></a></p>
<h5><a id="FOOT3" href="#DOCF3">(3)</a></h5>
<p>Guile (before v1.8) used to offer dedicated operations to sum arrays, etc. but obviously that isn&rsquo;t any kind of solution.</p>
<h5><a id="FOOT4" href="#DOCF4">(4)</a></h5>
<p>An exception is <a href="#x_002dra_002dindex_002dmap_0021"><code>ra-index-map!</code></a>, where passing the indices is the purpose.</p>
<h5><a id="FOOT5" href="#DOCF5">(5)</a></h5>
<p>Note that this is not the same as <code>(let ((d (vector-ref (ra-dims a) k))) (ra-iota (dim-len d) (dim-lo d)))</code>, because the lower bound of <code>(ra-iota ...)</code> (<em>not</em> its content) is 0, not <code>(dim-lo d)</code>, so the corresponding lower bound on the result array would also be 0, while <code>#t</code> preserves the lower bound of <code>a</code>.</p>
<h5><a id="FOOT6" href="#DOCF6">(6)</a></h5>
<p>An example of how using lower bounds other than 0 is generally worthless trouble, not least for the library author.</p>
<h5><a id="FOOT7" href="#DOCF7">(7)</a></h5>
<p>I decided against this approach for <code>newra</code> because in my experience it results in errors going undetected much more often than it saves any work.</p>
<h5><a id="FOOT8" href="#DOCF8">(8)</a></h5>
<p><a href="https://www.gnu.org/software/guile/manual/html_node/Formatted-Output.html"><code>(ice-9 format)</code></a></p>
<h5><a id="FOOT9" href="#DOCF9">(9)</a></h5>
<p>Cf. <code>array-index</code> from [<a href="#Sources">SRFI-164</a>]
.</p>
<h5><a id="FOOT10" href="#DOCF10">(10)</a></h5>
<p>This works because <a href="#x_002dra_002dorder_002dc_003f"><code>ra-order-c?</code></a> is always true for the result of <code>ra-copy</code>. Note that the ravel operation in <code>(ra-ravel (ra-copy ra))</code> is free, while it might not be in <code>(ra-copy (ra-ravel ra))</code>, so it is preferable, in principle, to copy first.</p>
<h5><a id="FOOT11" href="#DOCF11">(11)</a></h5>
<p>Cf. <code>array-index-ref</code> from [<a href="#Sources">SRFI-164</a>]
.</p>
</div>



</body>
</html>
